diff --git a/AGENTS.md b/AGENTS.md index 7900cfc..f61cbc9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ Lutra ("An otterly perfect IDE") is a clean-room, open-source PHP IDE targeting - Behaviour comes only from public documentation (jetbrains.com/help, public blog posts, public issue trackers and forum posts), cited by URL in `plan/phpstorm/`, and from the PHP language itself (php.net, the PHP RFCs, PSR specifications). - Feature names may be used to describe behaviour ("Go to Class", "Find Usages"). Wording, icons, colour schemes and default keymaps are not copied; Lutra ships its own. - If a task seems to need any of this, stop and say so instead. `cargo xtask cleanroom` (run by `cargo xtask ci`) fails on JetBrains copyright notices and on files that look like exported JetBrains configuration. -- Never copy GPL/AGPL/LGPL code. Dependencies must be under a permissive licence (MIT, Apache-2.0, BSD, ISC, Zlib, MPL-2.0 as a separate crate/package only; Unicode-3.0, approved by the owner on 2026-10-14 for unicode-ident and the ICU4X crates). `cargo deny` and the frontend licence check enforce it. +- Never copy GPL/AGPL/LGPL code. Dependencies must be under a permissive licence (MIT, Apache-2.0, BSD, ISC, Zlib, MPL-2.0 as a separate crate/package only; Unicode-3.0, approved by the owner on 2026-10-14 for unicode-ident and the ICU4X crates; CC0-1.0 for the notify crate only, approved by the owner on 2026-10-14). `cargo deny` and the frontend licence check enforce it. ### Assets: no JetBrains iconography or images, ever (absolute rule, from the project owner) - Never add, copy, trace, redraw from, embed or ship any icon, image, cursor, colour scheme, keymap, live template, file template or screenshot from JetBrains products or from any source whose licence doesn't allow it. diff --git a/Cargo.lock b/Cargo.lock index b50ec71..6b50560 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -400,6 +400,16 @@ dependencies = [ "tinyvec", ] +[[package]] +name = "bstr" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6bb31b46c14244e20ee9984b11bf5c992b91fb6939fea616e3512c8baecdbe5f" +dependencies = [ + "memchr", + "serde_core", +] + [[package]] name = "bumpalo" version = "3.20.3" @@ -733,6 +743,25 @@ dependencies = [ "crossbeam-utils", ] +[[package]] +name = "crossbeam-deque" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a" +dependencies = [ + "crossbeam-epoch", + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-epoch" +version = "0.9.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d" +dependencies = [ + "crossbeam-utils", +] + [[package]] name = "crossbeam-utils" version = "0.8.23" @@ -1297,6 +1326,15 @@ dependencies = [ "percent-encoding", ] +[[package]] +name = "fsevent-sys" +version = "4.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76ee7a02da4d231650c7cea31349b889be2f45ddb3ef3032d2ec8185f6313fd2" +dependencies = [ + "libc", +] + [[package]] name = "futures-channel" version = "0.3.34" @@ -1643,6 +1681,19 @@ version = "0.3.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b" +[[package]] +name = "globset" +version = "0.4.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07c34a9410465b45bd9787443bc7370f37735bad04b0f0cd57ff1a3186c98988" +dependencies = [ + "aho-corasick", + "bstr", + "log", + "regex-automata", + "regex-syntax", +] + [[package]] name = "gobject-sys" version = "0.18.0" @@ -1978,6 +2029,22 @@ dependencies = [ "icu_properties", ] +[[package]] +name = "ignore" +version = "0.4.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00b69833ed729dc5aa7d19541d96d6cf8e9137194207a04916d658e43168402f" +dependencies = [ + "crossbeam-deque", + "globset", + "log", + "memchr", + "regex-automata", + "same-file", + "walkdir", + "winapi-util", +] + [[package]] name = "image" version = "0.25.10" @@ -2023,6 +2090,26 @@ dependencies = [ "cfb", ] +[[package]] +name = "inotify" +version = "0.11.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cc00ea907cab49550b7da656f80ebb97be1b997d931fbcd28d39734e17ce592" +dependencies = [ + "bitflags 2.13.2", + "inotify-sys", + "libc", +] + +[[package]] +name = "inotify-sys" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c033f80b2c113cdf91ab7a33faa9cbc014726dcad99880c8609af2a370edf37d" +dependencies = [ + "libc", +] + [[package]] name = "ipnet" version = "2.12.2" @@ -2225,6 +2312,26 @@ version = "3.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc" +[[package]] +name = "kqueue" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d763e5b24120b4ddf50de6c92308156765aabfbbccebf401da7cff2d70a41ea" +dependencies = [ + "kqueue-sys", + "libc", +] + +[[package]] +name = "kqueue-sys" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07293a4e297ac234359b510362495713f75ea345d5307140414f20c69ffeb087" +dependencies = [ + "bitflags 2.13.2", + "libc", +] + [[package]] name = "libappindicator" version = "0.9.0" @@ -2461,6 +2568,12 @@ dependencies = [ [[package]] name = "lutra-vfs" version = "0.0.0" +dependencies = [ + "ignore", + "notify", + "tempfile", + "thiserror 2.0.21", +] [[package]] name = "markup5ever" @@ -2536,6 +2649,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" dependencies = [ "libc", + "log", "wasi", "windows-sys 0.61.2", ] @@ -2620,6 +2734,33 @@ dependencies = [ "memchr", ] +[[package]] +name = "notify" +version = "8.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3" +dependencies = [ + "bitflags 2.13.2", + "fsevent-sys", + "inotify", + "kqueue", + "libc", + "log", + "mio", + "notify-types", + "walkdir", + "windows-sys 0.60.2", +] + +[[package]] +name = "notify-types" +version = "2.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a" +dependencies = [ + "bitflags 2.13.2", +] + [[package]] name = "num-conv" version = "0.2.2" @@ -5451,6 +5592,15 @@ dependencies = [ "windows-targets 0.52.6", ] +[[package]] +name = "windows-sys" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb" +dependencies = [ + "windows-targets 0.53.5", +] + [[package]] name = "windows-sys" version = "0.61.2" @@ -5484,13 +5634,30 @@ dependencies = [ "windows_aarch64_gnullvm 0.52.6", "windows_aarch64_msvc 0.52.6", "windows_i686_gnu 0.52.6", - "windows_i686_gnullvm", + "windows_i686_gnullvm 0.52.6", "windows_i686_msvc 0.52.6", "windows_x86_64_gnu 0.52.6", "windows_x86_64_gnullvm 0.52.6", "windows_x86_64_msvc 0.52.6", ] +[[package]] +name = "windows-targets" +version = "0.53.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3" +dependencies = [ + "windows-link 0.2.1", + "windows_aarch64_gnullvm 0.53.1", + "windows_aarch64_msvc 0.53.1", + "windows_i686_gnu 0.53.1", + "windows_i686_gnullvm 0.53.1", + "windows_i686_msvc 0.53.1", + "windows_x86_64_gnu 0.53.1", + "windows_x86_64_gnullvm 0.53.1", + "windows_x86_64_msvc 0.53.1", +] + [[package]] name = "windows-threading" version = "0.1.0" @@ -5530,6 +5697,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53" + [[package]] name = "windows_aarch64_msvc" version = "0.42.2" @@ -5542,6 +5715,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" +[[package]] +name = "windows_aarch64_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006" + [[package]] name = "windows_i686_gnu" version = "0.42.2" @@ -5554,12 +5733,24 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" +[[package]] +name = "windows_i686_gnu" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3" + [[package]] name = "windows_i686_gnullvm" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" +[[package]] +name = "windows_i686_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c" + [[package]] name = "windows_i686_msvc" version = "0.42.2" @@ -5572,6 +5763,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" +[[package]] +name = "windows_i686_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2" + [[package]] name = "windows_x86_64_gnu" version = "0.42.2" @@ -5584,6 +5781,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" +[[package]] +name = "windows_x86_64_gnu" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499" + [[package]] name = "windows_x86_64_gnullvm" version = "0.42.2" @@ -5596,6 +5799,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1" + [[package]] name = "windows_x86_64_msvc" version = "0.42.2" @@ -5608,6 +5817,12 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" +[[package]] +name = "windows_x86_64_msvc" +version = "0.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" + [[package]] name = "winnow" version = "0.5.40" diff --git a/Cargo.toml b/Cargo.toml index 51f8e8b..a16f8b2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,6 +25,9 @@ lutra-mcp = { path = "crates/mcp" } lutra-testkit = { path = "crates/testkit" } ropey = { version = "1.6.1", default-features = false, features = ["cr_lines", "simd"] } proptest = "1.12.0" +ignore = "0.4.33" +notify = "8.2.0" +tempfile = "3.27.0" [workspace.lints.rust] missing_docs = "deny" diff --git a/NOTICE b/NOTICE index 38625d4..69f51d6 100644 --- a/NOTICE +++ b/NOTICE @@ -19,6 +19,7 @@ Bundled components (planned; update when added): * tree-sitter and tree-sitter-php — MIT License * Tauri — MIT OR Apache-2.0 * unicode-ident and ICU4X crates (via Tauri) — Unicode License v3 (Unicode-3.0) + * notify (file watching) — Creative Commons Zero v1.0 Universal (CC0-1.0) External tools Lutra talks to but does not bundle: * Phpactor (language server) — MIT License diff --git a/crates/vfs/Cargo.toml b/crates/vfs/Cargo.toml index 14eb854..aa5b2c2 100644 --- a/crates/vfs/Cargo.toml +++ b/crates/vfs/Cargo.toml @@ -12,6 +12,12 @@ publish.workspace = true layer = 2 [dependencies] +ignore.workspace = true +notify.workspace = true +thiserror = "2.0.21" + +[dev-dependencies] +tempfile.workspace = true [lints] workspace = true diff --git a/crates/vfs/src/error.rs b/crates/vfs/src/error.rs new file mode 100644 index 0000000..b9e4eca --- /dev/null +++ b/crates/vfs/src/error.rs @@ -0,0 +1,103 @@ +//! The error type of the VFS. +//! +//! Every fallible operation in this crate returns [`VfsError`]. It is `Clone` +//! and `PartialEq` so the engine can store it, compare it in tests and turn it +//! into a message for the user; I/O errors are kept as their kind plus text. + +use std::io; +use std::path::{Path, PathBuf}; + +/// Everything that can go wrong in the VFS. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum VfsError { + /// The path does not exist. + #[error("{} does not exist", path.display())] + NotFound { + /// The missing path. + path: PathBuf, + }, + /// A directory was expected but the path is something else. + #[error("{} is not a directory", path.display())] + NotADirectory { + /// The offending path. + path: PathBuf, + }, + /// A regular file was expected but the path is a directory or has no file name. + #[error("{} is not a file", path.display())] + NotAFile { + /// The offending path. + path: PathBuf, + }, + /// A project-relative path is absolute or climbs out of the project with `..`. + #[error("{} is outside the project", path.display())] + OutsideProject { + /// The rejected path, as given by the caller. + path: PathBuf, + }, + /// A file is larger than the read limit. + #[error("{} is {size} bytes, more than the limit of {limit} bytes", path.display())] + TooLarge { + /// The file. + path: PathBuf, + /// Its size in bytes (at least `limit + 1` when the file grew while reading). + size: u64, + /// The limit that was exceeded. + limit: u64, + }, + /// A file is not valid UTF-8. + #[error("{} is not valid UTF-8 (first invalid byte at offset {valid_up_to})", path.display())] + InvalidUtf8 { + /// The file. + path: PathBuf, + /// Byte offset in the file (including any BOM) of the first invalid byte. + valid_up_to: usize, + }, + /// A file starts with the byte order mark of an encoding Lutra cannot decode yet. + #[error("{} is encoded as {encoding}, which is not supported yet", path.display())] + UnsupportedEncoding { + /// The file. + path: PathBuf, + /// Name of the detected encoding, e.g. `UTF-16LE`. + encoding: &'static str, + }, + /// A file is marked read-only, so it is not overwritten. + #[error("{} is read-only", path.display())] + ReadOnly { + /// The file. + path: PathBuf, + }, + /// Any other I/O failure. + #[error("{}: {message}", path.display())] + Io { + /// The path the operation was about. + path: PathBuf, + /// The kind of the underlying error. + kind: io::ErrorKind, + /// The text of the underlying error. + message: String, + }, + /// File watching could not be started or stopped working; the project + /// stays usable without it. + #[error("file watching is unavailable: {message}")] + WatchUnavailable { + /// Why watching is unavailable. + message: String, + }, +} + +impl VfsError { + /// Converts an I/O error about `path`, mapping "not found" to + /// [`VfsError::NotFound`] and everything else to [`VfsError::Io`]. + pub(crate) fn io(path: &Path, err: io::Error) -> Self { + match err.kind() { + io::ErrorKind::NotFound => VfsError::NotFound { + path: path.to_path_buf(), + }, + kind => VfsError::Io { + path: path.to_path_buf(), + kind, + message: err.to_string(), + }, + } + } +} diff --git a/crates/vfs/src/io.rs b/crates/vfs/src/io.rs new file mode 100644 index 0000000..d288be9 --- /dev/null +++ b/crates/vfs/src/io.rs @@ -0,0 +1,216 @@ +//! Reading and writing files safely. +//! +//! Reads are capped ([`DEFAULT_READ_LIMIT`]) because files on disk are +//! untrusted. Text is UTF-8, with or without a byte order mark; other +//! encodings are detected by their BOM and reported, not guessed. Writes go +//! to a temporary file in the same directory that is then renamed over the +//! target, so a crash never leaves a half-written file behind. + +use std::fs::{self, File, OpenOptions}; +use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +use crate::VfsError; + +/// Default read limit: 32 MiB. +pub const DEFAULT_READ_LIMIT: u64 = 32 * 1024 * 1024; + +/// The UTF-8 byte order mark. +const UTF8_BOM: &[u8] = &[0xEF, 0xBB, 0xBF]; + +/// Byte order marks of encodings that are recognised but not decoded yet, +/// longest first so UTF-32LE is not mistaken for UTF-16LE. +const OTHER_BOMS: &[(&[u8], &str)] = &[ + (&[0xFF, 0xFE, 0x00, 0x00], "UTF-32LE"), + (&[0x00, 0x00, 0xFE, 0xFF], "UTF-32BE"), + (&[0xFF, 0xFE], "UTF-16LE"), + (&[0xFE, 0xFF], "UTF-16BE"), +]; + +/// Attempts to find a free temporary file name before giving up. +const TEMP_ATTEMPTS: u32 = 100; + +/// Counter that makes temporary file names unique within the process. +static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0); + +/// A decoded text file. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TextFile { + /// The text, without the byte order mark. + pub text: String, + /// The file started with a UTF-8 byte order mark; keep it when saving. + pub bom: bool, +} + +/// Reads at most `limit` bytes of the file at `path`. +/// +/// # Errors +/// [`VfsError::NotFound`], [`VfsError::NotAFile`] for a directory, +/// [`VfsError::TooLarge`] if the file is (or grows while reading) larger than +/// `limit`, [`VfsError::Io`] for other failures. +pub fn read_bytes(path: &Path, limit: u64) -> Result, VfsError> { + let file = File::open(path).map_err(|err| VfsError::io(path, err))?; + let meta = file.metadata().map_err(|err| VfsError::io(path, err))?; + if meta.is_dir() { + return Err(VfsError::NotAFile { + path: path.to_path_buf(), + }); + } + let too_large = |size| VfsError::TooLarge { + path: path.to_path_buf(), + size, + limit, + }; + if meta.len() > limit { + return Err(too_large(meta.len())); + } + let capacity = usize::try_from(meta.len()).unwrap_or(0); + let mut bytes = Vec::with_capacity(capacity); + file.take(limit.saturating_add(1)) + .read_to_end(&mut bytes) + .map_err(|err| VfsError::io(path, err))?; + let read = u64::try_from(bytes.len()).unwrap_or(u64::MAX); + if read > limit { + return Err(too_large(read)); + } + Ok(bytes) +} + +/// Reads the text file at `path` with the [`DEFAULT_READ_LIMIT`]. +/// +/// # Errors +/// See [`read_text_with_limit`]. +pub fn read_text(path: &Path) -> Result { + read_text_with_limit(path, DEFAULT_READ_LIMIT) +} + +/// Reads and decodes the text file at `path`, reading at most `limit` bytes. +/// +/// # Errors +/// Everything [`read_bytes`] returns, plus +/// [`VfsError::UnsupportedEncoding`] for a UTF-16 or UTF-32 BOM and +/// [`VfsError::InvalidUtf8`] for bytes that are not UTF-8. +pub fn read_text_with_limit(path: &Path, limit: u64) -> Result { + decode(path, read_bytes(path, limit)?) +} + +/// Decodes file contents as UTF-8 with an optional BOM; `path` is only used +/// in errors. +/// +/// # Errors +/// [`VfsError::UnsupportedEncoding`] or [`VfsError::InvalidUtf8`]. +pub fn decode(path: &Path, mut bytes: Vec) -> Result { + let bom = bytes.starts_with(UTF8_BOM); + if bom { + bytes.drain(..UTF8_BOM.len()); + } else if let Some((_, encoding)) = OTHER_BOMS.iter().find(|(mark, _)| bytes.starts_with(mark)) + { + return Err(VfsError::UnsupportedEncoding { + path: path.to_path_buf(), + encoding, + }); + } + let offset = if bom { UTF8_BOM.len() } else { 0 }; + match String::from_utf8(bytes) { + Ok(text) => Ok(TextFile { text, bom }), + Err(err) => Err(VfsError::InvalidUtf8 { + path: path.to_path_buf(), + valid_up_to: err.utf8_error().valid_up_to() + offset, + }), + } +} + +/// Writes `text` to `path` atomically as UTF-8, with a BOM if `bom` is set. +/// +/// # Errors +/// See [`write_atomic`]. +pub fn write_text(path: &Path, text: &str, bom: bool) -> Result<(), VfsError> { + let mut bytes = Vec::with_capacity(text.len() + UTF8_BOM.len()); + if bom { + bytes.extend_from_slice(UTF8_BOM); + } + bytes.extend_from_slice(text.as_bytes()); + write_atomic(path, &bytes) +} + +/// Replaces the contents of `path` with `bytes` atomically. +/// +/// The bytes go to a temporary file next to the target, which is flushed to +/// disk, given the target's permissions and renamed over it. Readers see +/// either the old or the new contents, never a mix. If `path` is a symbolic +/// link, the file it points to is replaced and the link kept. A new file is +/// created if `path` does not exist. File ownership is not carried over on +/// Unix (the new file belongs to the current user). If anything fails the +/// temporary file is removed; failing to remove it is ignored because the +/// write error is the one worth reporting. +/// +/// # Errors +/// [`VfsError::NotAFile`] if `path` is a directory or has no file name, +/// [`VfsError::ReadOnly`] if the target is read-only, [`VfsError::Io`] (or +/// [`VfsError::NotFound`] for a missing parent directory) otherwise. +pub fn write_atomic(path: &Path, bytes: &[u8]) -> Result<(), VfsError> { + let target = match fs::symlink_metadata(path) { + Ok(meta) if meta.file_type().is_symlink() => { + fs::canonicalize(path).map_err(|err| VfsError::io(path, err))? + } + _ => path.to_path_buf(), + }; + let existing = match fs::metadata(&target) { + Ok(meta) => Some(meta), + Err(err) if err.kind() == io::ErrorKind::NotFound => None, + Err(err) => return Err(VfsError::io(&target, err)), + }; + if let Some(meta) = &existing { + if meta.is_dir() { + return Err(VfsError::NotAFile { path: target }); + } + if meta.permissions().readonly() { + return Err(VfsError::ReadOnly { path: target }); + } + } + let Some(name) = target.file_name() else { + return Err(VfsError::NotAFile { path: target }); + }; + let dir = match target.parent() { + Some(parent) if !parent.as_os_str().is_empty() => parent.to_path_buf(), + _ => PathBuf::from("."), + }; + let (temp, mut file) = create_temp(&dir, name).map_err(|err| VfsError::io(&dir, err))?; + let result = (|| { + file.write_all(bytes)?; + if let Some(meta) = &existing { + fs::set_permissions(&temp, meta.permissions())?; + } + file.sync_all()?; + drop(file); + fs::rename(&temp, &target) + })(); + if let Err(err) = result { + let _cleanup_failure_is_secondary = fs::remove_file(&temp); + return Err(VfsError::io(&target, err)); + } + Ok(()) +} + +/// Creates a new, uniquely named hidden file in `dir` for writing `name`. +/// +/// # Errors +/// The I/O error of the last attempt. +fn create_temp(dir: &Path, name: &std::ffi::OsStr) -> io::Result<(PathBuf, File)> { + let mut last = io::Error::new(io::ErrorKind::AlreadyExists, "no free temporary file name"); + for _ in 0..TEMP_ATTEMPTS { + let serial = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed); + let temp = dir.join(format!( + ".{}.lutra-{}-{serial}.tmp", + name.to_string_lossy(), + std::process::id() + )); + match OpenOptions::new().write(true).create_new(true).open(&temp) { + Ok(file) => return Ok((temp, file)), + Err(err) if err.kind() == io::ErrorKind::AlreadyExists => last = err, + Err(err) => return Err(err), + } + } + Err(last) +} diff --git a/crates/vfs/src/lib.rs b/crates/vfs/src/lib.rs index 77c9617..7e27e2b 100644 --- a/crates/vfs/src/lib.rs +++ b/crates/vfs/src/lib.rs @@ -1,4 +1,58 @@ //! Virtual file system for Lutra (layer L2). //! -//! Models an open project: its roots, ignore rules, file watching and text -//! encodings. File contents read here are untrusted input. +//! Models an open project: its root, lazy directory listing, ignore rules, +//! file watching and text encodings. File contents and names read here are +//! untrusted input: sizes and counts are capped and nothing panics on odd +//! data. +//! +//! # Projects and listing +//! [`Project::open`] canonicalises the root (on Windows without the `\\?\` +//! prefix where that is safe) and reads nothing below it. +//! [`Project::children`] lists one directory on demand, sorted directories +//! first, then by case-insensitive name, each [`Entry`] with its kind, an +//! `ignored` flag and an [`EntryRole`]. Paths in the API are relative to the +//! project root; `..` and absolute paths are rejected. +//! +//! # Ignore rules +//! An entry is `ignored` when `.gitignore`, `.ignore`, `.git/info/exclude` +//! or the global git excludes file match it or one of its ancestors (see the +//! `rules` module for precedence). Rules apply whether or not the folder is a +//! git repository, and match case-sensitively. Ignored entries are still +//! listed; the UI dims them. +//! +//! Lutra's defaults, applied on top of the ignore files: +//! - `.git` (directory or file) at any depth is hidden: never listed, +//! watched or reported. +//! - `vendor/` directly under the root (Composer's default `vendor-dir`) is +//! [`EntryRole::Library`]: listed, not ignored, treated as third-party code. +//! - `node_modules/` at any depth is [`EntryRole::Excluded`]: listed, but +//! not watched or indexed. +//! +//! Roles are inherited: everything below `vendor/` is a library, everything +//! below `node_modules/` excluded. +//! +//! # Watching +//! [`Project::watch`] returns a [`Watcher`] and a channel of [`VfsEvent`]s; +//! see the `watch` module for the native backend (`notify`), its polling +//! fallback and their limits. +//! +//! # File IO +//! [`read_text`] reads up to [`DEFAULT_READ_LIMIT`] bytes and decodes UTF-8 +//! with an optional BOM; [`write_atomic`] and [`write_text`] replace a file +//! through a temporary file and a rename, keeping its permissions. + +mod error; +mod io; +mod path; +mod project; +mod rules; +mod watch; + +pub use error::VfsError; +pub use io::{ + DEFAULT_READ_LIMIT, TextFile, decode, read_bytes, read_text, read_text_with_limit, + write_atomic, write_text, +}; +pub use project::{Entry, EntryKind, Listing, MAX_CHILDREN, PathStatus, Project, ProjectOptions}; +pub use rules::{EntryRole, GlobalExcludes}; +pub use watch::{VfsEvent, WatchBackend, WatchOptions, Watcher}; diff --git a/crates/vfs/src/path.rs b/crates/vfs/src/path.rs new file mode 100644 index 0000000..d2a75d7 --- /dev/null +++ b/crates/vfs/src/path.rs @@ -0,0 +1,97 @@ +//! Path helpers: project-relative path validation and Windows prefix cleanup. + +use std::path::{Component, Path, PathBuf}; + +use crate::VfsError; + +/// Validates a project-relative path and returns it normalised. +/// +/// `.` components are dropped; an empty result means the project root. +/// +/// # Errors +/// [`VfsError::OutsideProject`] if the path is absolute, has a drive or UNC +/// prefix, or contains `..`. +pub(crate) fn check_relative(rel: &Path) -> Result { + let mut out = PathBuf::new(); + for component in rel.components() { + match component { + Component::Normal(part) => out.push(part), + Component::CurDir => {} + Component::ParentDir | Component::RootDir | Component::Prefix(_) => { + return Err(VfsError::OutsideProject { + path: rel.to_path_buf(), + }); + } + } + } + Ok(out) +} + +/// Turns a canonical Windows path like `\\?\C:\dir` back into `C:\dir` so it +/// reads naturally and compares equal to paths users type. +/// +/// The verbatim form is kept when the plain form could mean something else: +/// paths of 260 characters or more, and components ending in a dot or a +/// space. On other platforms the path is returned unchanged. +pub(crate) fn simplify(path: PathBuf) -> PathBuf { + if !cfg!(windows) { + return path; + } + let Some(text) = path.to_str() else { + return path; + }; + let Some(rest) = text.strip_prefix(r"\\?\") else { + return path; + }; + let bytes = rest.as_bytes(); + let is_disk = bytes.first().is_some_and(u8::is_ascii_alphabetic) + && bytes.get(1) == Some(&b':') + && bytes.get(2) == Some(&b'\\'); + let safe_parts = rest + .split('\\') + .all(|part| !part.ends_with('.') && !part.ends_with(' ')); + if is_disk && rest.len() < 260 && safe_parts { + PathBuf::from(rest) + } else { + path + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn relative_paths_are_normalised() { + assert_eq!( + check_relative(Path::new("./src/./a.php")).unwrap(), + Path::new("src").join("a.php") + ); + assert_eq!(check_relative(Path::new("")).unwrap(), PathBuf::new()); + } + + #[test] + fn escaping_paths_are_rejected() { + assert!(check_relative(Path::new("../x")).is_err()); + assert!(check_relative(Path::new("a/../../x")).is_err()); + let absolute = std::env::temp_dir(); + assert!(check_relative(&absolute).is_err()); + } + + #[cfg(windows)] + #[test] + fn verbatim_disk_prefix_is_stripped() { + assert_eq!( + simplify(PathBuf::from(r"\\?\C:\work\demo")), + PathBuf::from(r"C:\work\demo") + ); + assert_eq!( + simplify(PathBuf::from(r"\\?\C:\work\odd.")), + PathBuf::from(r"\\?\C:\work\odd.") + ); + assert_eq!( + simplify(PathBuf::from(r"\\?\UNC\server\share")), + PathBuf::from(r"\\?\UNC\server\share") + ); + } +} diff --git a/crates/vfs/src/project.rs b/crates/vfs/src/project.rs new file mode 100644 index 0000000..970d086 --- /dev/null +++ b/crates/vfs/src/project.rs @@ -0,0 +1,256 @@ +//! The opened project folder and lazy directory listing. + +use std::cmp::Ordering; +use std::ffi::OsStr; +use std::fs; +use std::path::{Path, PathBuf}; +use std::sync::Arc; + +use crate::VfsError; +use crate::path::{check_relative, simplify}; +use crate::rules::{EntryRole, GlobalExcludes, Globals, RuleChain, default_role, is_hidden}; + +/// Most entries returned for one directory; [`Listing::truncated`] reports +/// when a directory has more. +pub const MAX_CHILDREN: usize = 100_000; + +/// Options for [`Project::open_with`]. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct ProjectOptions { + /// Where the global git excludes come from. + pub global_excludes: GlobalExcludes, +} + +/// An opened project folder. +/// +/// Cheap to clone; clones share the project-wide ignore rules. Paths passed +/// to and returned from its methods are relative to [`Project::root`] unless +/// stated otherwise. +#[derive(Debug, Clone)] +pub struct Project { + /// Canonical absolute root. + root: PathBuf, + /// Rules loaded at open time (`.git/info/exclude`, global excludes). + globals: Arc, +} + +/// Kind of a directory entry. Symbolic links are reported as their target's +/// kind. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum EntryKind { + /// A regular file. + File, + /// A directory. + Directory, + /// Anything else: a broken symbolic link, a socket, a device. + Other, +} + +/// One entry of a directory listing. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Entry { + /// File name for display (lossy if the name is not valid Unicode). + pub name: String, + /// Path relative to the project root. + pub path: PathBuf, + /// What the entry is. + pub kind: EntryKind, + /// Matched by an ignore rule, directly or through an ignored ancestor. + pub ignored: bool, + /// Lutra's role for the entry, inherited from ancestors. + pub role: EntryRole, +} + +/// The children of one directory, sorted directories first, then by +/// case-insensitive name. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Listing { + /// The entries. + pub entries: Vec, + /// The directory had more than [`MAX_CHILDREN`] entries; the rest are + /// missing. + pub truncated: bool, +} + +/// Classification of one path inside the project. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PathStatus { + /// The path or an ancestor is `.git`. + pub hidden: bool, + /// The path or an ancestor matches an ignore rule. + pub ignored: bool, + /// The strongest role of the path and its ancestors. + pub role: EntryRole, +} + +impl Project { + /// Opens the folder at `path` with default options. + /// + /// # Errors + /// See [`Project::open_with`]. + pub fn open(path: impl AsRef) -> Result { + Self::open_with(path, ProjectOptions::default()) + } + + /// Opens the folder at `path`: canonicalises it and loads the + /// project-wide ignore rules. Nothing below the root is read. + /// + /// # Errors + /// [`VfsError::NotFound`] if the path does not exist, + /// [`VfsError::NotADirectory`] if it is not a directory, [`VfsError::Io`] + /// if it cannot be resolved. + pub fn open_with(path: impl AsRef, options: ProjectOptions) -> Result { + let path = path.as_ref(); + let root = simplify(fs::canonicalize(path).map_err(|err| VfsError::io(path, err))?); + let meta = fs::metadata(&root).map_err(|err| VfsError::io(&root, err))?; + if !meta.is_dir() { + return Err(VfsError::NotADirectory { path: root }); + } + let globals = Arc::new(Globals::load(&root, &options.global_excludes)); + Ok(Project { root, globals }) + } + + /// The canonical absolute root of the project. + pub fn root(&self) -> &Path { + &self.root + } + + /// Turns a project-relative path into an absolute one. + /// + /// # Errors + /// [`VfsError::OutsideProject`] if `rel` is absolute or contains `..`. + pub fn resolve(&self, rel: impl AsRef) -> Result { + Ok(self.root.join(check_relative(rel.as_ref())?)) + } + + /// Turns an absolute path below the root into a project-relative one; + /// `None` if it lies outside the project. The path is compared as given, + /// without resolving symbolic links. + pub fn relative(&self, abs: impl AsRef) -> Option { + let abs = simplify(abs.as_ref().to_path_buf()); + abs.strip_prefix(&self.root) + .ok() + .and_then(|rel| check_relative(rel).ok()) + } + + /// Lists the children of the directory `dir` (project-relative; empty for + /// the root). + /// + /// Reads only that directory and the ignore files of it and its + /// ancestors. `.git` entries are left out. Entries that cannot be + /// inspected are reported as [`EntryKind::Other`]. + /// + /// # Errors + /// [`VfsError::OutsideProject`] for an escaping path, + /// [`VfsError::NotFound`] / [`VfsError::NotADirectory`] if `dir` is not a + /// directory, [`VfsError::Io`] if it cannot be read. + pub fn children(&self, dir: impl AsRef) -> Result { + let dir = check_relative(dir.as_ref())?; + let abs = self.root.join(&dir); + let meta = fs::metadata(&abs).map_err(|err| VfsError::io(&abs, err))?; + if !meta.is_dir() { + return Err(VfsError::NotADirectory { path: abs }); + } + let parent = self.status(&dir)?; + let chain = RuleChain::load(&self.root, &dir, &self.globals); + let depth = chain.len(); + let reader = fs::read_dir(&abs).map_err(|err| VfsError::io(&abs, err))?; + let mut entries = Vec::new(); + let mut truncated = false; + for item in reader { + let Ok(item) = item else { + continue; + }; + let name = item.file_name(); + if is_hidden(&name) { + continue; + } + if entries.len() >= MAX_CHILDREN { + truncated = true; + break; + } + let path = dir.join(&name); + let kind = entry_kind(&item); + let is_dir = kind == EntryKind::Directory; + let ignored = parent.ignored || chain.is_ignored(&path, is_dir, depth); + let role = parent.role.max(default_role(&name, depth, is_dir)); + entries.push(Entry { + name: name.to_string_lossy().into_owned(), + path, + kind, + ignored, + role, + }); + } + entries.sort_by(compare_entries); + Ok(Listing { entries, truncated }) + } + + /// Classifies the project-relative path `rel` (which need not exist; a + /// missing path is classified as a file). + /// + /// # Errors + /// [`VfsError::OutsideProject`] for an escaping path. + pub fn status(&self, rel: impl AsRef) -> Result { + let rel = check_relative(rel.as_ref())?; + let mut status = PathStatus { + hidden: false, + ignored: false, + role: EntryRole::Normal, + }; + let Some(parent) = rel.parent() else { + return Ok(status); + }; + let chain = RuleChain::load(&self.root, parent, &self.globals); + let count = rel.components().count(); + let mut prefix = PathBuf::new(); + for (index, component) in rel.components().enumerate() { + let name: &OsStr = component.as_os_str(); + prefix.push(name); + let depth = index + 1; + let is_dir = depth < count || self.root.join(&prefix).is_dir(); + status.hidden |= is_hidden(name); + status.ignored = status.ignored || chain.is_ignored(&prefix, is_dir, depth); + status.role = status.role.max(default_role(name, depth, is_dir)); + } + Ok(status) + } +} + +/// Kind of a directory entry, following symbolic links. +fn entry_kind(item: &fs::DirEntry) -> EntryKind { + let Ok(file_type) = item.file_type() else { + return EntryKind::Other; + }; + let resolved = if file_type.is_symlink() { + match fs::metadata(item.path()) { + Ok(meta) => meta.file_type(), + Err(_) => return EntryKind::Other, + } + } else { + file_type + }; + kind_of(resolved) +} + +/// Maps a file type to an [`EntryKind`]. +pub(crate) fn kind_of(file_type: fs::FileType) -> EntryKind { + if file_type.is_dir() { + EntryKind::Directory + } else if file_type.is_file() { + EntryKind::File + } else { + EntryKind::Other + } +} + +/// Listing order: directories first, then case-insensitive name, then the +/// exact name so the order is total. +fn compare_entries(a: &Entry, b: &Entry) -> Ordering { + let a_dir = a.kind == EntryKind::Directory; + let b_dir = b.kind == EntryKind::Directory; + b_dir + .cmp(&a_dir) + .then_with(|| a.name.to_lowercase().cmp(&b.name.to_lowercase())) + .then_with(|| a.name.cmp(&b.name)) +} diff --git a/crates/vfs/src/rules.rs b/crates/vfs/src/rules.rs new file mode 100644 index 0000000..90b174a --- /dev/null +++ b/crates/vfs/src/rules.rs @@ -0,0 +1,205 @@ +//! Ignore rules and Lutra's default roles for well-known directories. +//! +//! Rules are read from disk on every query, top-down from the project root to +//! the directory being listed, so edits to `.gitignore` take effect on the next +//! listing without any cache to invalidate. Precedence, highest first, follows +//! the `ignore` crate: the deepest directory wins over its parents; within one +//! directory `.ignore` wins over `.gitignore`; then `.git/info/exclude`, then +//! the global git excludes file. A negated pattern (`!keep.log`) re-includes a +//! path, but nothing re-includes a path whose parent directory is ignored. + +use std::fs::File; +use std::io::Read; +use std::path::{Path, PathBuf}; + +use ignore::gitignore::{Gitignore, GitignoreBuilder}; + +/// Largest ignore file read, in bytes; the rest of a longer file is skipped. +const MAX_RULES_FILE: u64 = 1024 * 1024; + +/// What Lutra does with an entry besides showing it. +/// +/// Ordered by strength: an entry inherits the strongest role of its ancestors, +/// so `vendor/pkg/node_modules` is [`EntryRole::Excluded`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum EntryRole { + /// Ordinary project content. + Normal, + /// Third-party code (Composer's `vendor/`): shown, indexed for navigation, + /// not treated as project sources. + Library, + /// Shown dimmed but neither indexed nor watched (`node_modules/`). + Excluded, +} + +/// Where the global git excludes come from. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub enum GlobalExcludes { + /// Git's `core.excludesFile`, or `$XDG_CONFIG_HOME/git/ignore` when unset. + #[default] + GitConfig, + /// No global excludes (useful for tests and sandboxes). + None, + /// A specific file in gitignore format, matched relative to the project root. + File(PathBuf), +} + +/// Project-wide rules loaded once when the project opens. +#[derive(Debug)] +pub(crate) struct Globals { + /// `.git/info/exclude` of the project root, if present. + exclude: Option, + /// The global excludes file, if any. + global: Option, +} + +impl Globals { + /// Loads the project-wide rules for the project at `root`. + /// + /// A missing or unreadable file means "no rules"; ignore files are hints, + /// so failing to read one must not stop the project from opening. + pub(crate) fn load(root: &Path, source: &GlobalExcludes) -> Self { + let exclude = load_file(root, &root.join(".git").join("info").join("exclude")); + let global = match source { + GlobalExcludes::GitConfig => { + let (matcher, _partial_error) = GitignoreBuilder::new(root).build_global(); + (!matcher.is_empty()).then_some(matcher) + } + GlobalExcludes::None => None, + GlobalExcludes::File(path) => load_file(root, path), + }; + Globals { exclude, global } + } +} + +/// The ignore files of one directory. +struct Level { + /// The directory, relative to the project root. + dir: PathBuf, + /// Its `.ignore` file. + ignore: Option, + /// Its `.gitignore` file. + gitignore: Option, +} + +/// Ignore rules of a directory and all its ancestors up to the project root. +pub(crate) struct RuleChain<'p> { + /// One level per directory, the project root first. + levels: Vec, + /// Project-wide rules. + globals: &'p Globals, +} + +impl<'p> RuleChain<'p> { + /// Reads the ignore files of `dir` (project-relative, normalised) and of + /// every ancestor up to `root`. + pub(crate) fn load(root: &Path, dir: &Path, globals: &'p Globals) -> Self { + let mut levels = Vec::new(); + let mut rel = PathBuf::new(); + levels.push(Level::load(root, &rel)); + for component in dir.components() { + rel.push(component); + levels.push(Level::load(root, &rel)); + } + RuleChain { levels, globals } + } + + /// Whether `rel` (project-relative) matches an ignore rule, using only the + /// first `depth` levels of the chain (the directories that contain it). + /// + /// Ancestors of `rel` are not checked here; callers carry an inherited + /// flag instead. + pub(crate) fn is_ignored(&self, rel: &Path, is_dir: bool, depth: usize) -> bool { + let levels = self.levels.get(..depth).unwrap_or(&self.levels); + for level in levels.iter().rev() { + let Ok(sub) = rel.strip_prefix(&level.dir) else { + continue; + }; + for matcher in [&level.ignore, &level.gitignore].into_iter().flatten() { + if let Some(ignored) = decide(matcher, sub, is_dir) { + return ignored; + } + } + } + for matcher in [&self.globals.exclude, &self.globals.global] + .into_iter() + .flatten() + { + if let Some(ignored) = decide(matcher, rel, is_dir) { + return ignored; + } + } + false + } + + /// Number of levels, i.e. the depth of the listed directory plus one. + pub(crate) fn len(&self) -> usize { + self.levels.len() + } +} + +impl Level { + /// Loads the ignore files of the directory `rel` below `root`. + fn load(root: &Path, rel: &Path) -> Self { + let dir = root.join(rel); + Level { + dir: rel.to_path_buf(), + ignore: load_file(&dir, &dir.join(".ignore")), + gitignore: load_file(&dir, &dir.join(".gitignore")), + } + } +} + +/// `Some(true)` if the matcher ignores the path, `Some(false)` if it +/// whitelists it, `None` if no pattern matches. +fn decide(matcher: &Gitignore, path: &Path, is_dir: bool) -> Option { + let found = matcher.matched(path, is_dir); + if found.is_ignore() { + Some(true) + } else if found.is_whitelist() { + Some(false) + } else { + None + } +} + +/// Builds a matcher from the gitignore-format `file`, with patterns relative +/// to `base`. +/// +/// Returns `None` if the file is missing, unreadable or has no usable +/// pattern. At most [`MAX_RULES_FILE`] bytes are read, invalid UTF-8 is +/// replaced and invalid glob lines are skipped, matching git's tolerance. +fn load_file(base: &Path, file: &Path) -> Option { + let handle = File::open(file).ok()?; + let mut bytes = Vec::new(); + handle.take(MAX_RULES_FILE).read_to_end(&mut bytes).ok()?; + let text = String::from_utf8_lossy(&bytes); + let mut builder = GitignoreBuilder::new(base); + for line in text.lines() { + let _skipped_invalid_glob = builder.add_line(None, line); + } + let matcher = builder.build().ok()?; + (!matcher.is_empty()).then_some(matcher) +} + +/// Lutra's own role for an entry, before inheritance. +/// +/// `name` is the entry's file name, `depth` its number of path components +/// (1 for children of the root). +pub(crate) fn default_role(name: &std::ffi::OsStr, depth: usize, is_dir: bool) -> EntryRole { + if !is_dir { + EntryRole::Normal + } else if name == "node_modules" { + EntryRole::Excluded + } else if name == "vendor" && depth == 1 { + EntryRole::Library + } else { + EntryRole::Normal + } +} + +/// Whether an entry is never shown: `.git` (directory, or the file used by +/// worktrees and submodules) at any depth. +pub(crate) fn is_hidden(name: &std::ffi::OsStr) -> bool { + name == ".git" +} diff --git a/crates/vfs/src/watch.rs b/crates/vfs/src/watch.rs new file mode 100644 index 0000000..eb15487 --- /dev/null +++ b/crates/vfs/src/watch.rs @@ -0,0 +1,639 @@ +//! Watching the project for changes on disk. +//! +//! Two backends sit behind one API: +//! - **Native** (default): operating-system notifications through the +//! `notify` crate (ReadDirectoryChangesW, inotify, FSEvents). A +//! notification only marks its directory as dirty; once no notification +//! has arrived for [`WatchOptions::interval`] (100 ms by default, at most +//! ten intervals after the first one) the dirty directories are rescanned. +//! - **Polling** (fallback): every interval all watched directories are +//! rescanned. Used when the native watcher cannot start for the root +//! (network drives, exhausted inotify limits) or when +//! [`WatchBackend::Polling`] is requested, and for single directories the +//! native watcher refuses. +//! +//! Either way, events come from comparing kind, size and modification time +//! of each entry with the previous scan, so both backends report the same +//! events. Behaviour: +//! - Only watched directories are scanned, non-recursively. The root is +//! watched from the start; callers add the directories the user expanded +//! with [`Watcher::watch_dir`]. Directories that are hidden (`.git`), +//! ignored or excluded (`node_modules`) are refused, so no events come +//! from inside them, and `.git` entries are never reported. +//! - Changes within one debounce window are coalesced: several writes give +//! one [`VfsEvent::Modified`], a file created and deleted again gives +//! nothing. An entry that disappears while one with the same kind, size +//! and modification time appears in the same scan is reported as +//! [`VfsEvent::Renamed`]. +//! - Directories report creation, removal and renames of their children, +//! but not [`VfsEvent::Modified`] for themselves. +//! - A watched directory that disappears stops being watched (its parent +//! reports the removal if watched). If the root cannot be read the watcher +//! sends [`VfsEvent::Failed`] and stops: the project keeps working without +//! watching. If the native watcher reports an error or lost events, all +//! watched directories are rescanned. +//! - A change that keeps size and modification time is not seen; modern file +//! systems record modification times finely enough for this to be rare. + +use std::collections::{BTreeMap, BTreeSet, HashMap}; +use std::ffi::OsString; +use std::fs; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender}; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; +use std::thread::{self, JoinHandle}; +use std::time::{Duration, Instant, SystemTime}; + +use notify::{RecommendedWatcher, RecursiveMode, Watcher as _}; + +use crate::VfsError; +use crate::path::check_relative; +use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of}; +use crate::rules::{EntryRole, is_hidden}; + +/// Longest debounce, in intervals, while notifications keep arriving. +const MAX_DEBOUNCE_INTERVALS: u32 = 10; + +/// Which backend [`Project::watch_with`] uses. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub enum WatchBackend { + /// Native notifications, falling back to polling if they fail to start. + #[default] + Auto, + /// Polling only. + Polling, +} + +/// Options for [`Project::watch_with`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct WatchOptions { + /// Debounce window, and the time between scans when polling. + pub interval: Duration, + /// The backend to use. + pub backend: WatchBackend, +} + +impl Default for WatchOptions { + fn default() -> Self { + WatchOptions { + interval: Duration::from_millis(100), + backend: WatchBackend::Auto, + } + } +} + +/// A change on disk. Paths are relative to the project root. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum VfsEvent { + /// An entry appeared. + Created { + /// The new entry. + path: PathBuf, + /// Its kind. + kind: EntryKind, + }, + /// A file's contents changed. + Modified { + /// The file. + path: PathBuf, + }, + /// An entry disappeared. + Removed { + /// The removed entry. + path: PathBuf, + }, + /// An entry was moved within the watched directories. + Renamed { + /// The old path. + from: PathBuf, + /// The new path. + to: PathBuf, + }, + /// Watching stopped; no further events follow. + Failed(VfsError), +} + +/// A running watcher. Dropping it stops the background thread. +#[derive(Debug)] +pub struct Watcher { + /// State shared with the thread. + shared: Arc, + /// Wakes the thread when the watcher is dropped. + signals: Sender, + /// The background thread, joined on drop. + thread: Option>, +} + +/// State shared between the [`Watcher`] handle and its thread. +#[derive(Debug)] +struct Shared { + /// The project being watched. + project: Project, + /// Set to ask the thread to stop. + stop: AtomicBool, + /// Every watched directory, keyed by project-relative path. + dirs: Mutex>, + /// The native watcher, if it started. + native: Mutex>, +} + +/// One watched directory. +#[derive(Debug)] +struct Watched { + /// Its last scan. + snapshot: Snapshot, + /// The native watcher covers it; otherwise it is polled. + native: bool, +} + +/// Messages to the background thread. +#[derive(Debug)] +enum Signal { + /// Something changed at these absolute paths. + Paths(Vec), + /// The native watcher lost events or failed; rescan everything. + Rescan, + /// The watcher was dropped. + Stop, +} + +/// What the next scan has to look at. +#[derive(Default)] +struct Work { + /// Natively watched directories with notifications, project-relative. + dirty: BTreeSet, + /// Rescan every directory. + full: bool, +} + +/// Entries of one directory by name. +type Snapshot = HashMap; + +/// What a scan remembers about an entry. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +struct Stamp { + /// Entry kind. + kind: EntryKind, + /// Size in bytes. + len: u64, + /// Modification time, if the platform reports one. + modified: Option, +} + +/// Changes found by one scan, before rename pairing. +#[derive(Default)] +struct Changes { + /// Entries that appeared. + created: Vec<(PathBuf, Stamp)>, + /// Entries that disappeared. + removed: Vec<(PathBuf, Stamp)>, + /// Files whose stamp changed. + modified: Vec, +} + +impl Project { + /// Starts watching with default options. + /// + /// # Errors + /// See [`Project::watch_with`]. + pub fn watch(&self) -> Result<(Watcher, Receiver), VfsError> { + self.watch_with(WatchOptions::default()) + } + + /// Starts watching the project root; events arrive on the returned + /// channel. Changes made after this returns are reported. A native + /// watcher that fails to start is not an error: the watcher polls + /// instead (see [`Watcher::is_native`]). + /// + /// # Errors + /// [`VfsError::WatchUnavailable`] if the root cannot be scanned or the + /// thread cannot be started. The project stays usable; callers carry on + /// without watching and show the error. + pub fn watch_with( + &self, + options: WatchOptions, + ) -> Result<(Watcher, Receiver), VfsError> { + let (signals, signal_receiver) = mpsc::channel(); + let native = match options.backend { + WatchBackend::Auto => start_native(self.root(), signals.clone()), + WatchBackend::Polling => None, + }; + let snapshot = scan(self.root()).map_err(|err| VfsError::WatchUnavailable { + message: format!("cannot read {}: {err}", self.root().display()), + })?; + let mut dirs = BTreeMap::new(); + dirs.insert( + PathBuf::new(), + Watched { + snapshot, + native: native.is_some(), + }, + ); + let shared = Arc::new(Shared { + project: self.clone(), + stop: AtomicBool::new(false), + dirs: Mutex::new(dirs), + native: Mutex::new(native), + }); + let (sender, receiver) = mpsc::channel(); + let thread_shared = Arc::clone(&shared); + let thread = thread::Builder::new() + .name("lutra-vfs-watch".into()) + .spawn(move || run(&thread_shared, &signal_receiver, &sender, options.interval)) + .map_err(|err| VfsError::WatchUnavailable { + message: format!("cannot start the watcher thread: {err}"), + })?; + Ok(( + Watcher { + shared, + signals, + thread: Some(thread), + }, + receiver, + )) + } +} + +/// Starts a native watcher on `root` that forwards notifications as +/// [`Signal`]s; `None` if the platform refuses. A send to a stopped thread +/// fails and is ignored: nobody is left to care about the notification. +fn start_native(root: &Path, signals: Sender) -> Option { + let handler = move |result: notify::Result| { + let signal = match result { + Ok(event) if event.need_rescan() => Signal::Rescan, + Ok(event) => Signal::Paths(event.paths), + Err(_) => Signal::Rescan, + }; + let _thread_gone = signals.send(signal); + }; + let mut watcher = notify::recommended_watcher(handler).ok()?; + watcher.watch(root, RecursiveMode::NonRecursive).ok()?; + Some(watcher) +} + +impl Watcher { + /// Starts watching the directory `dir` (project-relative). Returns + /// `false` without watching if the directory is hidden, ignored or + /// excluded; watching an already watched directory is a no-op. If the + /// native watcher refuses the directory, it is polled instead. + /// + /// # Errors + /// [`VfsError::OutsideProject`] for an escaping path, [`VfsError::NotFound`] + /// or [`VfsError::Io`] if the directory cannot be read. + pub fn watch_dir(&self, dir: impl AsRef) -> Result { + let dir = check_relative(dir.as_ref())?; + let status = self.shared.project.status(&dir)?; + if status.hidden || status.ignored || status.role == EntryRole::Excluded { + return Ok(false); + } + if self.shared.lock().contains_key(&dir) { + return Ok(true); + } + let abs = self.shared.project.root().join(&dir); + let native = self + .shared + .lock_native() + .as_mut() + .is_some_and(|watcher| watcher.watch(&abs, RecursiveMode::NonRecursive).is_ok()); + let snapshot = match scan(&abs) { + Ok(snapshot) => snapshot, + Err(err) => { + self.shared.unwatch_native(&abs); + return Err(VfsError::io(&abs, err)); + } + }; + self.shared + .lock() + .entry(dir) + .or_insert(Watched { snapshot, native }); + Ok(true) + } + + /// Stops watching the directory `dir` (project-relative). Unknown + /// directories are ignored. + pub fn unwatch_dir(&self, dir: impl AsRef) { + let Ok(dir) = check_relative(dir.as_ref()) else { + return; + }; + let removed = self.shared.lock().remove(&dir); + if removed.is_some_and(|watched| watched.native) { + self.shared + .unwatch_native(&self.shared.project.root().join(&dir)); + } + } + + /// The watched directories, project-relative, sorted. + pub fn watched_dirs(&self) -> Vec { + self.shared.lock().keys().cloned().collect() + } + + /// Whether the project root is watched natively (`false`: polling). + pub fn is_native(&self) -> bool { + self.shared + .lock() + .get(Path::new("")) + .is_some_and(|watched| watched.native) + } +} + +impl Drop for Watcher { + /// Stops the native watcher, then stops and joins the thread. A failed + /// wake-up send means the thread already ended, and a panic inside the + /// thread is not propagated: the watcher is going away and has nothing + /// left to report. + fn drop(&mut self) { + self.shared.stop.store(true, Ordering::SeqCst); + let native = self.shared.lock_native().take(); + drop(native); + let _thread_gone = self.signals.send(Signal::Stop); + if let Some(thread) = self.thread.take() { + let _thread_result = thread.join(); + } + } +} + +impl Shared { + /// Locks the watched directories. A poisoned lock is recovered: + /// entries are only replaced whole, so they are consistent even after a + /// panic. + fn lock(&self) -> MutexGuard<'_, BTreeMap> { + self.dirs.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// Locks the native watcher, recovering a poisoned lock like + /// [`Shared::lock`]. + fn lock_native(&self) -> MutexGuard<'_, Option> { + self.native.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// Removes the native watch on the absolute directory `abs`. Failure is + /// ignored: the directory may already be gone, which ends its watch + /// anyway. + fn unwatch_native(&self, abs: &Path) { + if let Some(watcher) = self.lock_native().as_mut() { + let _already_gone = watcher.unwatch(abs); + } + } +} + +impl Work { + /// Records a signal; `false` for [`Signal::Stop`]. + fn add(&mut self, signal: Signal, project: &Project) -> bool { + match signal { + Signal::Paths(paths) => { + for path in paths { + if let Some(rel) = project.relative(&path) { + if let Some(parent) = rel.parent() { + self.dirty.insert(parent.to_path_buf()); + } + self.dirty.insert(rel); + } + } + true + } + Signal::Rescan => { + self.full = true; + true + } + Signal::Stop => false, + } + } +} + +/// Body of the background thread: wait for notifications (debounced) or +/// the polling interval, scan, send; until stopped, until the receiver is +/// dropped or until the root fails. +fn run(shared: &Shared, signals: &Receiver, sender: &Sender, interval: Duration) { + loop { + let mut work = Work::default(); + match signals.recv_timeout(interval) { + Ok(signal) => { + if !work.add(signal, &shared.project) + || !debounce(shared, signals, interval, &mut work) + { + return; + } + } + Err(RecvTimeoutError::Timeout) => {} + Err(RecvTimeoutError::Disconnected) => return, + } + if shared.stop.load(Ordering::SeqCst) { + return; + } + let (events, failed) = poll(shared, &work); + for event in events { + if sender.send(event).is_err() { + return; + } + } + if failed { + return; + } + } +} + +/// Collects further signals until none arrives for `interval`, or for at +/// most [`MAX_DEBOUNCE_INTERVALS`] intervals. Returns `false` if the thread +/// must stop. +fn debounce( + shared: &Shared, + signals: &Receiver, + interval: Duration, + work: &mut Work, +) -> bool { + let deadline = Instant::now() + interval * MAX_DEBOUNCE_INTERVALS; + loop { + let left = deadline.saturating_duration_since(Instant::now()); + if left.is_zero() { + return true; + } + match signals.recv_timeout(interval.min(left)) { + Ok(signal) => { + if !work.add(signal, &shared.project) { + return false; + } + } + Err(RecvTimeoutError::Timeout) => return true, + Err(RecvTimeoutError::Disconnected) => return false, + } + } +} + +/// Rescans the polled directories and the dirty native ones (all of them +/// for a full rescan) and returns the events, plus whether watching failed +/// for good. The root is checked on every call, so its loss is noticed +/// even when no notification reports it. +fn poll(shared: &Shared, work: &Work) -> (Vec, bool) { + let root = shared.project.root(); + let mut dirs = shared.lock(); + let mut root_error = match fs::metadata(root) { + Ok(meta) if meta.is_dir() => None, + Ok(_) => Some("not a directory".to_string()), + Err(err) => Some(err.to_string()), + }; + let mut changes = Changes::default(); + let mut gone = Vec::new(); + if root_error.is_none() { + for (dir, watched) in dirs.iter_mut() { + if watched.native && !work.full && !work.dirty.contains(dir) { + continue; + } + match scan(&root.join(dir)) { + Ok(new) => { + diff(dir, &watched.snapshot, &new, &mut changes); + watched.snapshot = new; + } + Err(err) if dir.as_os_str().is_empty() => { + root_error = Some(err.to_string()); + break; + } + Err(_) => gone.push((dir.clone(), watched.native)), + } + } + } + if let Some(err) = root_error { + dirs.clear(); + drop(dirs); + let native = shared.lock_native().take(); + drop(native); + let failure = VfsError::WatchUnavailable { + message: format!("cannot read {}: {err}", root.display()), + }; + return (vec![VfsEvent::Failed(failure)], true); + } + for (dir, _) in &gone { + dirs.remove(dir); + } + drop(dirs); + for (dir, native) in gone { + if native { + shared.unwatch_native(&root.join(dir)); + } + } + (pair_renames(changes), false) +} + +/// Reads the entries of `dir`, skipping `.git` and stopping after +/// [`MAX_CHILDREN`] entries. +/// +/// # Errors +/// The I/O error of opening the directory; entries that vanish or cannot be +/// inspected while reading are skipped. +fn scan(dir: &Path) -> std::io::Result { + let mut snapshot = Snapshot::new(); + for item in fs::read_dir(dir)? { + if snapshot.len() >= MAX_CHILDREN { + break; + } + let Ok(item) = item else { + continue; + }; + let name = item.file_name(); + if is_hidden(&name) { + continue; + } + let Ok(meta) = fs::metadata(item.path()) else { + continue; + }; + let stamp = Stamp { + kind: kind_of(meta.file_type()), + len: meta.len(), + modified: meta.modified().ok(), + }; + snapshot.insert(name, stamp); + } + Ok(snapshot) +} + +/// Adds the differences between two scans of `dir` to `changes`. +fn diff(dir: &Path, old: &Snapshot, new: &Snapshot, changes: &mut Changes) { + for (name, stamp) in new { + match old.get(name) { + None => changes.created.push((dir.join(name), *stamp)), + Some(before) if before.kind != stamp.kind => { + changes.removed.push((dir.join(name), *before)); + changes.created.push((dir.join(name), *stamp)); + } + Some(before) if before != stamp && stamp.kind == EntryKind::File => { + changes.modified.push(dir.join(name)); + } + Some(_) => {} + } + } + for (name, stamp) in old { + if !new.contains_key(name) { + changes.removed.push((dir.join(name), *stamp)); + } + } +} + +/// Turns raw changes into events, pairing a removal and a creation with the +/// same stamp into a rename when that stamp is unique on both sides. +/// Events are ordered removals, renames, creations, modifications, each +/// sorted by path. +fn pair_renames(changes: Changes) -> Vec { + let Changes { + mut created, + mut removed, + mut modified, + } = changes; + let mut removed_by_stamp: HashMap> = HashMap::new(); + for (index, (_, stamp)) in removed.iter().enumerate() { + if stamp.modified.is_some() { + removed_by_stamp.entry(*stamp).or_default().push(index); + } + } + let mut created_by_stamp: HashMap = HashMap::new(); + for (_, stamp) in &created { + *created_by_stamp.entry(*stamp).or_default() += 1; + } + let mut renamed = Vec::new(); + let mut paired_removed = vec![false; removed.len()]; + let mut paired_created = vec![false; created.len()]; + for (index, (to, stamp)) in created.iter().enumerate() { + let Some(candidates) = removed_by_stamp.get(stamp) else { + continue; + }; + let [from_index] = candidates.as_slice() else { + continue; + }; + if created_by_stamp.get(stamp) != Some(&1) { + continue; + } + let Some((from, _)) = removed.get(*from_index) else { + continue; + }; + renamed.push(VfsEvent::Renamed { + from: from.clone(), + to: to.clone(), + }); + if let Some(flag) = paired_removed.get_mut(*from_index) { + *flag = true; + } + if let Some(flag) = paired_created.get_mut(index) { + *flag = true; + } + } + let mut keep = paired_removed.iter().map(|paired| !paired); + removed.retain(|_| keep.next().unwrap_or(true)); + let mut keep = paired_created.iter().map(|paired| !paired); + created.retain(|_| keep.next().unwrap_or(true)); + removed.sort_by(|a, b| a.0.cmp(&b.0)); + created.sort_by(|a, b| a.0.cmp(&b.0)); + modified.sort(); + let mut events = + Vec::with_capacity(removed.len() + renamed.len() + created.len() + modified.len()); + events.extend( + removed + .into_iter() + .map(|(path, _)| VfsEvent::Removed { path }), + ); + events.extend(renamed); + events.extend(created.into_iter().map(|(path, stamp)| VfsEvent::Created { + path, + kind: stamp.kind, + })); + events.extend(modified.into_iter().map(|path| VfsEvent::Modified { path })); + events +} diff --git a/crates/vfs/tests/common/mod.rs b/crates/vfs/tests/common/mod.rs new file mode 100644 index 0000000..d2bfb92 --- /dev/null +++ b/crates/vfs/tests/common/mod.rs @@ -0,0 +1,37 @@ +//! Helpers shared by the integration tests. + +#![allow(dead_code, clippy::unwrap_used)] + +use std::fs; +use std::path::Path; + +use lutra_vfs::{GlobalExcludes, Project, ProjectOptions}; +use tempfile::TempDir; + +/// Creates a temporary directory with the given files; a path ending in `/` +/// creates a directory. +pub fn tree(paths: &[(&str, &str)]) -> TempDir { + let dir = tempfile::tempdir().unwrap(); + for (path, contents) in paths { + let full = dir.path().join(path); + if path.ends_with('/') { + fs::create_dir_all(&full).unwrap(); + } else { + fs::create_dir_all(full.parent().unwrap()).unwrap(); + fs::write(&full, contents).unwrap(); + } + } + dir +} + +/// Opens `dir` without the machine's global git excludes, so tests don't +/// depend on the developer's configuration. +pub fn open(dir: &Path) -> Project { + Project::open_with( + dir, + ProjectOptions { + global_excludes: GlobalExcludes::None, + }, + ) + .unwrap() +} diff --git a/crates/vfs/tests/io.rs b/crates/vfs/tests/io.rs new file mode 100644 index 0000000..169d57c --- /dev/null +++ b/crates/vfs/tests/io.rs @@ -0,0 +1,193 @@ +//! Reading with limits and decoding; atomic writes. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +mod common; + +use std::fs; + +use common::tree; +use lutra_vfs::{VfsError, read_bytes, read_text, read_text_with_limit, write_atomic, write_text}; + +#[test] +fn reads_utf8_with_and_without_bom() { + let dir = tree(&[("plain.php", " = fs::read_dir(dir.path()) + .unwrap() + .map(|e| e.unwrap().file_name().into_string().unwrap()) + .collect(); + names.sort(); + assert_eq!(names, ["a.php", "created.php"]); +} + +#[test] +fn atomic_write_refuses_read_only_files_and_directories() { + let dir = tree(&[("locked.php", "keep"), ("sub/", "")]); + let path = dir.path().join("locked.php"); + let mut perms = fs::metadata(&path).unwrap().permissions(); + perms.set_readonly(true); + fs::set_permissions(&path, perms.clone()).unwrap(); + assert!(matches!( + write_atomic(&path, b"lost"), + Err(VfsError::ReadOnly { .. }) + )); + assert_eq!(fs::read(&path).unwrap(), b"keep"); + #[allow(clippy::permissions_set_readonly_false)] + perms.set_readonly(false); + fs::set_permissions(&path, perms).unwrap(); + assert!(matches!( + write_atomic(&dir.path().join("sub"), b"x"), + Err(VfsError::NotAFile { .. }) + )); + assert!(matches!( + write_atomic(&dir.path().join("missing").join("a.php"), b"x"), + Err(VfsError::NotFound { .. }) + )); +} + +#[cfg(unix)] +#[test] +fn atomic_write_keeps_permissions() { + use std::os::unix::fs::PermissionsExt; + let dir = tree(&[("run.sh", "#!/bin/sh")]); + let path = dir.path().join("run.sh"); + fs::set_permissions(&path, fs::Permissions::from_mode(0o751)).unwrap(); + write_atomic(&path, b"#!/bin/sh\necho hi").unwrap(); + let mode = fs::metadata(&path).unwrap().permissions().mode() & 0o777; + assert_eq!(mode, 0o751); +} + +#[cfg(unix)] +#[test] +fn atomic_write_through_a_symlink_keeps_the_link() { + let dir = tree(&[("real.php", "old")]); + let link = dir.path().join("link.php"); + std::os::unix::fs::symlink(dir.path().join("real.php"), &link).unwrap(); + write_atomic(&link, b"new").unwrap(); + assert!( + fs::symlink_metadata(&link) + .unwrap() + .file_type() + .is_symlink() + ); + assert_eq!(fs::read(dir.path().join("real.php")).unwrap(), b"new"); +} + +/// Decoding random bytes never panics, and valid UTF-8 round-trips with and +/// without a BOM. A small deterministic generator stands in for proptest. +#[test] +fn decode_never_panics_on_random_bytes() { + let mut state: u64 = 0x9E37_79B9_7F4A_7C15; + let mut next = move || { + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + state + }; + let path = std::path::Path::new("random.bin"); + for _ in 0..5_000 { + let len = (next() % 64) as usize; + let mut bytes: Vec = (0..len).map(|_| next() as u8).collect(); + if next() % 4 == 0 { + bytes.splice(0..0, [0xEF, 0xBB, 0xBF]); + } + match lutra_vfs::decode(path, bytes.clone()) { + Ok(file) => { + let mut again = if file.bom { + vec![0xEF, 0xBB, 0xBF] + } else { + Vec::new() + }; + again.extend_from_slice(file.text.as_bytes()); + assert_eq!(again, bytes); + } + Err(VfsError::InvalidUtf8 { valid_up_to, .. }) => assert!(valid_up_to < bytes.len()), + Err(VfsError::UnsupportedEncoding { .. }) => {} + Err(other) => panic!("unexpected error {other:?}"), + } + } +} diff --git a/crates/vfs/tests/project.rs b/crates/vfs/tests/project.rs new file mode 100644 index 0000000..d7d1db0 --- /dev/null +++ b/crates/vfs/tests/project.rs @@ -0,0 +1,228 @@ +//! Opening projects, listing order and ignore rules. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +mod common; + +use std::fs; +use std::path::{Path, PathBuf}; + +use common::{open, tree}; +use lutra_vfs::{Entry, EntryKind, EntryRole, GlobalExcludes, Project, ProjectOptions, VfsError}; + +fn names(entries: &[Entry]) -> Vec<&str> { + entries.iter().map(|e| e.name.as_str()).collect() +} + +fn entry<'a>(entries: &'a [Entry], name: &str) -> &'a Entry { + entries.iter().find(|e| e.name == name).unwrap() +} + +#[test] +fn open_canonicalises_the_root() { + let dir = tree(&[("src/", "")]); + let project = open(&dir.path().join("src").join("..")); + assert!(project.root().is_absolute()); + assert_eq!(project.root(), open(dir.path()).root()); + assert!(!project.root().to_string_lossy().starts_with(r"\\?\")); +} + +#[test] +fn open_rejects_missing_and_non_directory_paths() { + let dir = tree(&[("file.txt", "x")]); + let missing = Project::open(dir.path().join("nope")); + assert!(matches!(missing, Err(VfsError::NotFound { .. }))); + let file = Project::open(dir.path().join("file.txt")); + assert!(matches!(file, Err(VfsError::NotADirectory { .. }))); +} + +#[test] +fn children_sorts_directories_first_then_case_insensitive() { + let dir = tree(&[ + ("b.php", ""), + ("A.php", ""), + ("c.php", ""), + ("zeta/", ""), + ("Alpha/", ""), + ("beta/", ""), + ]); + let listing = open(dir.path()).children("").unwrap(); + assert_eq!( + names(&listing.entries), + ["Alpha", "beta", "zeta", "A.php", "b.php", "c.php"] + ); + assert!(!listing.truncated); + let alpha = entry(&listing.entries, "Alpha"); + assert_eq!(alpha.kind, EntryKind::Directory); + assert_eq!(alpha.path, PathBuf::from("Alpha")); + assert_eq!(entry(&listing.entries, "b.php").kind, EntryKind::File); +} + +#[test] +fn children_of_a_subdirectory_have_relative_paths() { + let dir = tree(&[("src/Controller/Home.php", "")]); + let listing = open(dir.path()).children("src").unwrap(); + assert_eq!(names(&listing.entries), ["Controller"]); + assert_eq!(listing.entries[0].path, Path::new("src").join("Controller")); + let inner = open(dir.path()).children("src/Controller").unwrap(); + assert_eq!( + inner.entries[0].path, + Path::new("src").join("Controller").join("Home.php") + ); +} + +#[test] +fn children_rejects_bad_paths() { + let dir = tree(&[("a.php", "")]); + let project = open(dir.path()); + assert!(matches!( + project.children("../"), + Err(VfsError::OutsideProject { .. }) + )); + assert!(matches!( + project.children("missing"), + Err(VfsError::NotFound { .. }) + )); + assert!(matches!( + project.children("a.php"), + Err(VfsError::NotADirectory { .. }) + )); +} + +#[test] +fn gitignore_marks_entries_and_their_descendants() { + let dir = tree(&[ + (".gitignore", "*.log\n/build/\n!keep.log\n"), + ("app.log", ""), + ("keep.log", ""), + ("index.php", ""), + ("build/out/a.txt", ""), + ("src/build/b.txt", ""), + ]); + let project = open(dir.path()); + let root = project.children("").unwrap().entries; + assert!(entry(&root, "app.log").ignored); + assert!(!entry(&root, "keep.log").ignored); + assert!(!entry(&root, "index.php").ignored); + assert!(entry(&root, "build").ignored); + assert!(!entry(&root, ".gitignore").ignored); + let build = project.children("build").unwrap().entries; + assert!(entry(&build, "out").ignored); + let deep = project.children("build/out").unwrap().entries; + assert!(entry(&deep, "a.txt").ignored); + let src = project.children("src").unwrap().entries; + assert!( + !entry(&src, "build").ignored, + "anchored pattern only at root" + ); +} + +#[test] +fn nested_gitignore_and_dot_ignore_take_precedence() { + let dir = tree(&[ + (".gitignore", "*.cache\n"), + ("sub/.gitignore", "!local.cache\n"), + ("sub/local.cache", ""), + ("sub/other.cache", ""), + (".ignore", "notes.md\n"), + ("notes.md", ""), + ("tool/.gitignore", "gen.php\n"), + ("tool/.ignore", "!gen.php\n"), + ("tool/gen.php", ""), + ]); + let project = open(dir.path()); + let sub = project.children("sub").unwrap().entries; + assert!(!entry(&sub, "local.cache").ignored); + assert!(entry(&sub, "other.cache").ignored); + let root = project.children("").unwrap().entries; + assert!(entry(&root, "notes.md").ignored); + let tool = project.children("tool").unwrap().entries; + assert!(!entry(&tool, "gen.php").ignored, ".ignore beats .gitignore"); +} + +#[test] +fn ignore_rule_edits_apply_to_the_next_listing() { + let dir = tree(&[("a.tmp", "")]); + let project = open(dir.path()); + assert!(!project.children("").unwrap().entries[0].ignored); + fs::write(dir.path().join(".gitignore"), "*.tmp\n").unwrap(); + let root = project.children("").unwrap().entries; + assert!(entry(&root, "a.tmp").ignored); +} + +#[test] +fn info_exclude_and_global_excludes_apply() { + let dir = tree(&[ + (".git/info/exclude", "secret.txt\n"), + ("secret.txt", ""), + ("global.bak", ""), + ("plain.txt", ""), + ]); + let global = tempfile::NamedTempFile::new().unwrap(); + fs::write(global.path(), "*.bak\n").unwrap(); + let project = Project::open_with( + dir.path(), + ProjectOptions { + global_excludes: GlobalExcludes::File(global.path().to_path_buf()), + }, + ) + .unwrap(); + let root = project.children("").unwrap().entries; + assert!(entry(&root, "secret.txt").ignored); + assert!(entry(&root, "global.bak").ignored); + assert!(!entry(&root, "plain.txt").ignored); +} + +#[test] +fn lutra_defaults_hide_git_and_mark_vendor_and_node_modules() { + let dir = tree(&[ + (".git/HEAD", "ref"), + ("vendor/acme/lib/A.php", ""), + ("vendor/acme/node_modules/x.js", ""), + ("node_modules/pkg/index.js", ""), + ("web/node_modules/y.js", ""), + ("src/vendor/", ""), + ("src/sub/.git", "gitdir: elsewhere"), + ]); + let project = open(dir.path()); + let root = project.children("").unwrap().entries; + assert_eq!(names(&root), ["node_modules", "src", "vendor", "web"]); + assert_eq!(entry(&root, "vendor").role, EntryRole::Library); + assert!(!entry(&root, "vendor").ignored); + assert_eq!(entry(&root, "node_modules").role, EntryRole::Excluded); + assert_eq!(entry(&root, "src").role, EntryRole::Normal); + let acme = project.children("vendor/acme").unwrap().entries; + assert_eq!(entry(&acme, "lib").role, EntryRole::Library); + assert_eq!(entry(&acme, "node_modules").role, EntryRole::Excluded); + let pkg = project.children("node_modules/pkg").unwrap().entries; + assert_eq!(entry(&pkg, "index.js").role, EntryRole::Excluded); + let web = project.children("web").unwrap().entries; + assert_eq!(entry(&web, "node_modules").role, EntryRole::Excluded); + let src = project.children("src").unwrap().entries; + assert_eq!(entry(&src, "vendor").role, EntryRole::Normal); + assert!(project.children("src/sub").unwrap().entries.is_empty()); + assert!(project.status(".git/HEAD").unwrap().hidden); +} + +#[test] +fn resolve_and_relative_round_trip() { + let dir = tree(&[("src/a.php", "")]); + let project = open(dir.path()); + let abs = project.resolve("src/a.php").unwrap(); + assert!(abs.is_file()); + assert_eq!( + project.relative(&abs).unwrap(), + Path::new("src").join("a.php") + ); + assert!( + project + .relative(std::env::temp_dir().join("elsewhere")) + .is_none() + ); + assert!(project.resolve("../x").is_err()); +} diff --git a/crates/vfs/tests/watch.rs b/crates/vfs/tests/watch.rs new file mode 100644 index 0000000..f297ac2 --- /dev/null +++ b/crates/vfs/tests/watch.rs @@ -0,0 +1,205 @@ +//! The watcher, run once per backend (native and polling). Every wait is +//! bounded by a timeout on the channel. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::indexing_slicing +)] + +mod common; + +use std::fs; +use std::path::{Path, PathBuf}; +use std::sync::mpsc::{Receiver, RecvTimeoutError}; +use std::time::{Duration, Instant}; + +use common::{open, tree}; +use lutra_vfs::{EntryKind, Project, VfsEvent, WatchBackend, WatchOptions, Watcher}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +/// Receives events until one satisfies `want`, failing after [`TIMEOUT`]. +/// Returns the events seen before it. +fn wait_for(rx: &Receiver, want: impl Fn(&VfsEvent) -> bool) -> Vec { + let deadline = Instant::now() + TIMEOUT; + let mut seen = Vec::new(); + loop { + let left = deadline.saturating_duration_since(Instant::now()); + match rx.recv_timeout(left) { + Ok(event) if want(&event) => return seen, + Ok(event) => seen.push(event), + Err(RecvTimeoutError::Timeout) => panic!("timed out; saw {seen:?}"), + Err(RecvTimeoutError::Disconnected) => panic!("watcher stopped; saw {seen:?}"), + } + } +} + +/// Starts a watcher with `backend`, checking that the native backend +/// really started on this machine. +fn start( + project: &Project, + backend: WatchBackend, + interval: Duration, +) -> (Watcher, Receiver) { + let (watcher, rx) = project + .watch_with(WatchOptions { interval, backend }) + .unwrap(); + assert_eq!(watcher.is_native(), backend == WatchBackend::Auto); + (watcher, rx) +} + +fn watch(project: &Project, backend: WatchBackend) -> (Watcher, Receiver) { + start(project, backend, WatchOptions::default().interval) +} + +/// Runs each listed test body once per backend. +macro_rules! both_backends { + ($($name:ident),* $(,)?) => { + mod native { + $(#[test] fn $name() { super::$name(super::WatchBackend::Auto) })* + } + mod polling { + $(#[test] fn $name() { super::$name(super::WatchBackend::Polling) })* + } + }; +} + +both_backends!( + reports_create_modify_rename_and_delete, + reports_directories_and_watched_subdirectories, + ignored_hidden_and_excluded_directories_are_not_watched, + changes_within_one_interval_are_coalesced, + losing_the_root_degrades_to_an_error_event, + dropping_the_watcher_closes_the_channel, +); + +fn is_created(path: &Path) -> impl Fn(&VfsEvent) -> bool + '_ { + move |e| matches!(e, VfsEvent::Created { path: p, .. } if p == path) +} + +fn reports_create_modify_rename_and_delete(backend: WatchBackend) { + let dir = tree(&[("keep.php", "")]); + let project = open(dir.path()); + let (_watcher, rx) = watch(&project, backend); + + fs::write(dir.path().join("new.php"), "a").unwrap(); + wait_for(&rx, is_created(Path::new("new.php"))); + + fs::write(dir.path().join("new.php"), "a longer body").unwrap(); + wait_for( + &rx, + |e| matches!(e, VfsEvent::Modified { path } if path == Path::new("new.php")), + ); + + fs::rename(dir.path().join("new.php"), dir.path().join("moved.php")).unwrap(); + wait_for(&rx, |e| { + *e == VfsEvent::Renamed { + from: PathBuf::from("new.php"), + to: PathBuf::from("moved.php"), + } + }); + + fs::remove_file(dir.path().join("moved.php")).unwrap(); + wait_for( + &rx, + |e| matches!(e, VfsEvent::Removed { path } if path == Path::new("moved.php")), + ); +} + +fn reports_directories_and_watched_subdirectories(backend: WatchBackend) { + let dir = tree(&[]); + let project = open(dir.path()); + let (watcher, rx) = watch(&project, backend); + fs::create_dir(dir.path().join("src")).unwrap(); + wait_for(&rx, |e| { + *e == VfsEvent::Created { + path: PathBuf::from("src"), + kind: EntryKind::Directory, + } + }); + assert!(watcher.watch_dir("src").unwrap()); + assert_eq!( + watcher.watched_dirs(), + [PathBuf::new(), PathBuf::from("src")] + ); + fs::write(dir.path().join("src").join("A.php"), "").unwrap(); + let inner = Path::new("src").join("A.php"); + wait_for(&rx, is_created(&inner)); + watcher.unwatch_dir("src"); + assert_eq!(watcher.watched_dirs(), [PathBuf::new()]); +} + +fn ignored_hidden_and_excluded_directories_are_not_watched(backend: WatchBackend) { + let dir = tree(&[ + (".gitignore", "target/\n"), + ("target/", ""), + ("node_modules/", ""), + (".git/", ""), + ("src/", ""), + ]); + let project = open(dir.path()); + let (watcher, rx) = watch(&project, backend); + assert!(!watcher.watch_dir("target").unwrap()); + assert!(!watcher.watch_dir("node_modules").unwrap()); + assert!(!watcher.watch_dir(".git").unwrap()); + assert!(watcher.watch_dir("src").unwrap()); + + fs::write(dir.path().join("target").join("out.bin"), "x").unwrap(); + fs::write(dir.path().join("node_modules").join("m.js"), "x").unwrap(); + fs::write(dir.path().join(".git").join("index"), "x").unwrap(); + fs::write(dir.path().join("src").join("marker.php"), "x").unwrap(); + let marker = Path::new("src").join("marker.php"); + let before = wait_for(&rx, is_created(&marker)); + for event in &before { + let text = format!("{event:?}"); + assert!( + !text.contains("target") && !text.contains("node_modules") && !text.contains(".git"), + "unexpected event {event:?}" + ); + } +} + +fn changes_within_one_interval_are_coalesced(backend: WatchBackend) { + let dir = tree(&[]); + let project = open(dir.path()); + let (_watcher, rx) = start(&project, backend, Duration::from_secs(2)); + let start = Instant::now(); + fs::write(dir.path().join("flash.tmp"), "x").unwrap(); + fs::remove_file(dir.path().join("flash.tmp")).unwrap(); + fs::write(dir.path().join("marker.php"), "x").unwrap(); + let before = wait_for(&rx, is_created(Path::new("marker.php"))); + let polled_once_at_most = start.elapsed() < Duration::from_secs(2); + if backend == WatchBackend::Auto || polled_once_at_most { + assert!(before.is_empty(), "flash.tmp leaked: {before:?}"); + } +} + +fn losing_the_root_degrades_to_an_error_event(backend: WatchBackend) { + let parent = tree(&[("project/a.php", "")]); + let root = parent.path().join("project"); + let project = open(&root); + let (_watcher, rx) = watch(&project, backend); + fs::remove_dir_all(&root).unwrap(); + wait_for(&rx, |e| matches!(e, VfsEvent::Failed(_))); + let deadline = Instant::now() + TIMEOUT; + loop { + match rx.recv_timeout(deadline.saturating_duration_since(Instant::now())) { + Ok(_) => continue, + Err(RecvTimeoutError::Disconnected) => break, + Err(RecvTimeoutError::Timeout) => panic!("watcher kept running"), + } + } +} + +fn dropping_the_watcher_closes_the_channel(backend: WatchBackend) { + let dir = tree(&[]); + let project = open(dir.path()); + let (watcher, rx) = watch(&project, backend); + drop(watcher); + assert_eq!( + rx.recv_timeout(TIMEOUT), + Err(RecvTimeoutError::Disconnected) + ); +} diff --git a/deny.toml b/deny.toml index 1224dbf..47934c8 100644 --- a/deny.toml +++ b/deny.toml @@ -24,5 +24,11 @@ allow = [ "Unicode-3.0", ] +# Crate-scoped exceptions, each approved by the owner. They do not widen +# the allow list for any other crate. +[[licenses.exceptions]] +crate = "notify" +allow = ["CC0-1.0"] + [licenses.private] ignore = true diff --git a/docs/gaps.md b/docs/gaps.md index b369a2e..f8ae4fa 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -8,7 +8,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t |---|---|---|---| | G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) | | G2 | Editor core: buffers, undo, multi-caret, save, recovery journal | M1 | ~30 h | -| G3 | Project model: VFS, file watching, project tree, tabs; command palette, settings, theme switching | M1 | ~30 h | +| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), project tree, tabs; command palette, settings, theme switching | M1 | ~27 h | | G4 | Syntax and structure: tree-sitter PHP, Lezer highlighting, file structure | M2 | ~15 h | | G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h | | G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor | M3 | ~45 h | @@ -36,5 +36,7 @@ Known smaller items from M0: | Date | Change | Summary | |---|---|---| | 2026-10-14 | minor | G2 note: text buffer landed (M1.1) | +| 2026-10-14 | minor | G3: native file watching (M1.2b); notify item resolved (CC0-1.0 approved for notify) | +| 2026-10-14 | minor | G3 shrunk by the VFS (M1.2); notify licence item | | 2026-10-14 | minor | G1 closed; estimates for G2–G16; M0 follow-ups | | 2026-10-13 | major | Initial gap list | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 0be9e7e..dec295d 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -13,7 +13,7 @@ Hours are the estimated agent wall-clock hours for one agent to reach behaviour | Area | Weight | Score | Missing | Hours (one agent) | Evidence | |---|---:|---:|---|---:|---| | Editor core | 12 | 0% | everything user-visible; only the engine text buffer exists | ~120 (est.) | `crates/text`: rope buffer, positions, edits (M1.1, unit tests + proptests) | -| Project view, VFS | 6 | 0% | everything | ~40 (est.) | — | +| Project view, VFS | 6 | 0% | everything visible: project tree, file commands | ~37 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), native file watching via `notify` with a polling fallback, capped UTF-8 reads, atomic writes; 34 tests on temp dirs, watcher tests run on both backends (`crates/vfs/tests`) | | Navigation | 10 | 0% | everything | ~120 (est.) | — | | Search and replace | 6 | 0% | everything | ~80 (est.) | — | | Code completion | 10 | 0% | everything | ~250 (est.) | — | @@ -53,13 +53,16 @@ No PHP feature. The foundation, verified on Windows 11: Nothing user-visible yet, so every score stays 0%. - M1.1 text buffer (`crates/text`): `Buffer` on a `ropey` rope with byte, char, UTF-16 and line counts; byte offset to line and column in UTF-16 code units or chars and back, all fallible (out of range, inside a character, inside a CRLF, inside a surrogate pair); atomic `Edit` batches in LSP `TextEdit[]` semantics that reject reversed, out-of-range and overlapping ranges; ` -` / ` -` / ` ` detection with a keep-the-file's-ending save policy. 23 unit tests and 6 proptests (round-trips on emoji, ZWJ sequences, CJK and combining marks; random edit batches checked against a `String` model, never panicking). +` / ` +` / ` +` detection with a keep-the-file's-ending save policy. 23 unit tests and 6 proptests (round-trips on emoji, ZWJ sequences, CJK and combining marks; random edit batches checked against a `String` model, never panicking). ## Revision history | Date | Change | Summary | |---|---|---| | 2026-10-14 | minor | M1.1 text buffer evidence (Editor core, score unchanged) | +| 2026-10-14 | minor | Project view evidence: native file watching (M1.2b), score unchanged | +| 2026-10-14 | minor | Project view evidence: `lutra-vfs` (M1.2), score unchanged | | 2026-10-14 | minor | Hours per area, weights reviewed, M0 evidence | | 2026-10-13 | major | Baseline |