From 5d49b57b9c6631a4215187d3ca59f7db173433cc Mon Sep 17 00:00:00 2001 From: danny Date: Wed, 14 Oct 2026 19:23:54 +0200 Subject: [PATCH] M1.2: vfs with ignore rules, polling watcher and safe file IO - Project::open canonicalises the root (no \?\ prefix on Windows where safe); typed errors for missing and non-directory paths. - Lazy children(dir): dirs first, case-insensitive; kind, ignored flag and role (vendor/ library, node_modules/ excluded, .git hidden). - Ignore rules via the ignore crate: .gitignore, .ignore, .git/info/exclude, global git excludes, with git precedence. - Watcher: std-only polling (100 ms, watched dirs only) with create/modify/remove/rename events and a Failed event on root loss. notify is CC0-1.0 and fails cargo deny; owner decision pending. - read_text with a 32 MiB cap, UTF-8 + BOM, typed InvalidUtf8 and UnsupportedEncoding; write_atomic via temp file + rename, keeping permissions and refusing read-only files. - 28 tests on temp dirs (30 on Unix: permission and symlink write tests). Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 63 +++++ Cargo.toml | 2 + crates/vfs/Cargo.toml | 5 + crates/vfs/src/error.rs | 103 ++++++++ crates/vfs/src/io.rs | 216 +++++++++++++++++ crates/vfs/src/lib.rs | 57 ++++- crates/vfs/src/path.rs | 97 ++++++++ crates/vfs/src/project.rs | 256 ++++++++++++++++++++ crates/vfs/src/rules.rs | 205 ++++++++++++++++ crates/vfs/src/watch.rs | 416 +++++++++++++++++++++++++++++++++ crates/vfs/tests/common/mod.rs | 37 +++ crates/vfs/tests/io.rs | 193 +++++++++++++++ crates/vfs/tests/project.rs | 228 ++++++++++++++++++ crates/vfs/tests/watch.rs | 174 ++++++++++++++ docs/gaps.md | 7 +- docs/target-app-parity.md | 3 +- 16 files changed, 2058 insertions(+), 4 deletions(-) create mode 100644 crates/vfs/src/error.rs create mode 100644 crates/vfs/src/io.rs create mode 100644 crates/vfs/src/path.rs create mode 100644 crates/vfs/src/project.rs create mode 100644 crates/vfs/src/rules.rs create mode 100644 crates/vfs/src/watch.rs create mode 100644 crates/vfs/tests/common/mod.rs create mode 100644 crates/vfs/tests/io.rs create mode 100644 crates/vfs/tests/project.rs create mode 100644 crates/vfs/tests/watch.rs diff --git a/Cargo.lock b/Cargo.lock index a08c740..bbd5559 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" @@ -1643,6 +1672,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 +2020,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" @@ -2457,6 +2515,11 @@ version = "0.0.0" [[package]] name = "lutra-vfs" version = "0.0.0" +dependencies = [ + "ignore", + "tempfile", + "thiserror 2.0.21", +] [[package]] name = "markup5ever" diff --git a/Cargo.toml b/Cargo.toml index a3abfb3..68149fe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -23,6 +23,8 @@ lutra-engine = { path = "crates/engine" } lutra-control = { path = "crates/control" } lutra-mcp = { path = "crates/mcp" } lutra-testkit = { path = "crates/testkit" } +ignore = "0.4.33" +tempfile = "3.27.0" [workspace.lints.rust] missing_docs = "deny" diff --git a/crates/vfs/Cargo.toml b/crates/vfs/Cargo.toml index 14eb854..582513e 100644 --- a/crates/vfs/Cargo.toml +++ b/crates/vfs/Cargo.toml @@ -12,6 +12,11 @@ publish.workspace = true layer = 2 [dependencies] +ignore.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..fadb3fe 100644 --- a/crates/vfs/src/lib.rs +++ b/crates/vfs/src/lib.rs @@ -1,4 +1,57 @@ //! 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 polling design and its 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, 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..47741ec --- /dev/null +++ b/crates/vfs/src/watch.rs @@ -0,0 +1,416 @@ +//! Watching the project for changes on disk. +//! +//! The watcher polls: a background thread re-reads the watched directories +//! every [`WatchOptions::interval`] (100 ms by default) and compares kind, +//! size and modification time of each entry with the previous scan. It needs +//! no dependency; native notifications (the `notify` crate) wait on a licence +//! decision and would sit behind the same API. +//! +//! 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 interval are coalesced (debounced): 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. +//! - 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, 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, Sender}; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; +use std::thread::{self, JoinHandle}; +use std::time::{Duration, SystemTime}; + +use crate::VfsError; +use crate::path::check_relative; +use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of}; +use crate::rules::{EntryRole, is_hidden}; + +/// Options for [`Project::watch_with`]. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct WatchOptions { + /// Time between scans; also the debounce window. + pub interval: Duration, +} + +impl Default for WatchOptions { + fn default() -> Self { + WatchOptions { + interval: Duration::from_millis(100), + } + } +} + +/// 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, + /// The polling 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, + /// Last scan of every watched directory, keyed by project-relative path. + dirs: Mutex>, +} + +/// 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. + /// + /// # 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 root = 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(), root); + let shared = Arc::new(Shared { + project: self.clone(), + stop: AtomicBool::new(false), + dirs: Mutex::new(dirs), + }); + 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, &sender, options.interval)) + .map_err(|err| VfsError::WatchUnavailable { + message: format!("cannot start the watcher thread: {err}"), + })?; + Ok(( + Watcher { + shared, + thread: Some(thread), + }, + receiver, + )) + } +} + +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. + /// + /// # 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 snapshot = scan(&abs).map_err(|err| VfsError::io(&abs, err))?; + self.shared.lock().entry(dir).or_insert(snapshot); + Ok(true) + } + + /// Stops watching the directory `dir` (project-relative). Unknown + /// directories are ignored. + pub fn unwatch_dir(&self, dir: impl AsRef) { + if let Ok(dir) = check_relative(dir.as_ref()) { + self.shared.lock().remove(&dir); + } + } + + /// The watched directories, project-relative, sorted. + pub fn watched_dirs(&self) -> Vec { + self.shared.lock().keys().cloned().collect() + } +} + +impl Drop for Watcher { + /// Stops and joins the polling thread. 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); + if let Some(thread) = self.thread.take() { + thread.thread().unpark(); + let _thread_result = thread.join(); + } + } +} + +impl Shared { + /// Locks the snapshots. A poisoned lock is recovered: snapshots 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) + } +} + +/// Body of the polling thread: scan, diff, send, until stopped, until the +/// receiver is dropped or until the root fails. +fn run(shared: &Shared, sender: &Sender, interval: Duration) { + loop { + thread::park_timeout(interval); + if shared.stop.load(Ordering::SeqCst) { + return; + } + let (events, failed) = poll(shared); + for event in events { + if sender.send(event).is_err() { + return; + } + } + if failed { + return; + } + } +} + +/// Rescans every watched directory and returns the events, plus whether +/// watching failed for good. +fn poll(shared: &Shared) -> (Vec, bool) { + let root = shared.project.root(); + let mut dirs = shared.lock(); + let mut changes = Changes::default(); + let mut gone = Vec::new(); + let mut root_error = None; + for (dir, old) in dirs.iter_mut() { + match scan(&root.join(dir)) { + Ok(new) => { + diff(dir, old, &new, &mut changes); + *old = new; + } + Err(err) if dir.as_os_str().is_empty() => { + root_error = Some(err); + break; + } + Err(_) => gone.push(dir.clone()), + } + } + if let Some(err) = root_error { + dirs.clear(); + let failure = VfsError::WatchUnavailable { + message: format!("cannot read {}: {err}", root.display()), + }; + return (vec![VfsEvent::Failed(failure)], true); + } + for dir in gone { + dirs.remove(&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..34171b8 --- /dev/null +++ b/crates/vfs/tests/watch.rs @@ -0,0 +1,174 @@ +//! The polling watcher. 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, VfsEvent, WatchOptions}; + +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:?}"), + } + } +} + +fn is_created(path: &Path) -> impl Fn(&VfsEvent) -> bool + '_ { + move |e| matches!(e, VfsEvent::Created { path: p, .. } if p == path) +} + +#[test] +fn reports_create_modify_rename_and_delete() { + let dir = tree(&[("keep.php", "")]); + let project = open(dir.path()); + let (_watcher, rx) = project.watch().unwrap(); + + 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")), + ); +} + +#[test] +fn reports_directories_and_watched_subdirectories() { + let dir = tree(&[]); + let project = open(dir.path()); + let (watcher, rx) = project.watch().unwrap(); + 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()]); +} + +#[test] +fn ignored_hidden_and_excluded_directories_are_not_watched() { + let dir = tree(&[ + (".gitignore", "target/\n"), + ("target/", ""), + ("node_modules/", ""), + (".git/", ""), + ("src/", ""), + ]); + let project = open(dir.path()); + let (watcher, rx) = project.watch().unwrap(); + 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:?}" + ); + } +} + +#[test] +fn changes_within_one_interval_are_coalesced() { + let dir = tree(&[]); + let project = open(dir.path()); + let (_watcher, rx) = project + .watch_with(WatchOptions { + interval: Duration::from_secs(2), + }) + .unwrap(); + 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"))); + if start.elapsed() < Duration::from_secs(2) { + assert!(before.is_empty(), "flash.tmp leaked: {before:?}"); + } +} + +#[test] +fn losing_the_root_degrades_to_an_error_event() { + let parent = tree(&[("project/a.php", "")]); + let root = parent.path().join("project"); + let project = open(&root); + let (_watcher, rx) = project.watch().unwrap(); + 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"), + } + } +} + +#[test] +fn dropping_the_watcher_closes_the_channel() { + let dir = tree(&[]); + let project = open(dir.path()); + let (watcher, rx) = project.watch().unwrap(); + drop(watcher); + assert_eq!( + rx.recv_timeout(TIMEOUT), + Err(RecvTimeoutError::Disconnected) + ); +} diff --git a/docs/gaps.md b/docs/gaps.md index ac33914..2a58dc1 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, polling watcher, safe file IO), native file watching, project tree, tabs; command palette, settings, theme switching | M1 | ~28 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 | @@ -29,9 +29,14 @@ Known smaller items from M0: - `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have. +Known smaller items from M1: + +- File watching polls (100 ms, watched directories only): `notify` is CC0-1.0 in every version and `cargo deny` rejects it. Owner decision pending; native events would plug in behind the same `Watcher` API. + ## Revision history | Date | Change | Summary | |---|---|---| +| 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 e83b7dc..928d967 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 | ~120 (est.) | — | -| Project view, VFS | 6 | 0% | everything | ~40 (est.) | — | +| Project view, VFS | 6 | 0% | everything visible: project tree, file commands, native file watching (only polling so far) | ~38 (est.) | `lutra-vfs` (M1.2): lazy sorted listing, ignore rules (.gitignore, .ignore, info/exclude, global excludes, Lutra defaults), polling watcher, capped UTF-8 reads, atomic writes; 28 tests on temp dirs (`crates/vfs/tests`) | | Navigation | 10 | 0% | everything | ~120 (est.) | — | | Search and replace | 6 | 0% | everything | ~80 (est.) | — | | Code completion | 10 | 0% | everything | ~250 (est.) | — | @@ -52,5 +52,6 @@ No PHP feature. The foundation, verified on Windows 11: | Date | Change | Summary | |---|---|---| +| 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 |