M1.2: native file watching via notify

- notify 8.2.0 (CC0-1.0) behind the existing Watcher API, allowed by a
  crate-scoped [[licenses.exceptions]] entry in deny.toml (owner
  decision 2026-10-14, noted in AGENTS.md and NOTICE).
- Native notifications only mark directories dirty; after 100 ms of
  quiet (at most 10 intervals) dirty dirs are rescanned and diffed, so
  events, debouncing and rename pairing match the polling backend.
- Polling stays as fallback when the native watcher cannot start, and
  per directory when a native watch is refused. Lost events or watcher
  errors trigger a full rescan; root loss is checked on every tick.
- Additive API: WatchOptions::backend (Auto, Polling) and
  Watcher::is_native.
- Watch tests run on both backends (34 vfs tests on Windows).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-14 19:43:15 +02:00
parent 5d49b57b9c
commit 3f190a635e
11 changed files with 500 additions and 86 deletions

View file

@ -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). - 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. - 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. - 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) ### 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. - 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.

154
Cargo.lock generated
View file

@ -1326,6 +1326,15 @@ dependencies = [
"percent-encoding", "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]] [[package]]
name = "futures-channel" name = "futures-channel"
version = "0.3.34" version = "0.3.34"
@ -2081,6 +2090,26 @@ dependencies = [
"cfb", "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]] [[package]]
name = "ipnet" name = "ipnet"
version = "2.12.2" version = "2.12.2"
@ -2283,6 +2312,26 @@ version = "3.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc" 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]] [[package]]
name = "libappindicator" name = "libappindicator"
version = "0.9.0" version = "0.9.0"
@ -2517,6 +2566,7 @@ name = "lutra-vfs"
version = "0.0.0" version = "0.0.0"
dependencies = [ dependencies = [
"ignore", "ignore",
"notify",
"tempfile", "tempfile",
"thiserror 2.0.21", "thiserror 2.0.21",
] ]
@ -2595,6 +2645,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee"
dependencies = [ dependencies = [
"libc", "libc",
"log",
"wasi", "wasi",
"windows-sys 0.61.2", "windows-sys 0.61.2",
] ]
@ -2679,6 +2730,33 @@ dependencies = [
"memchr", "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]] [[package]]
name = "num-conv" name = "num-conv"
version = "0.2.2" version = "0.2.2"
@ -5494,6 +5572,15 @@ dependencies = [
"windows-targets 0.52.6", "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]] [[package]]
name = "windows-sys" name = "windows-sys"
version = "0.61.2" version = "0.61.2"
@ -5527,13 +5614,30 @@ dependencies = [
"windows_aarch64_gnullvm 0.52.6", "windows_aarch64_gnullvm 0.52.6",
"windows_aarch64_msvc 0.52.6", "windows_aarch64_msvc 0.52.6",
"windows_i686_gnu 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_i686_msvc 0.52.6",
"windows_x86_64_gnu 0.52.6", "windows_x86_64_gnu 0.52.6",
"windows_x86_64_gnullvm 0.52.6", "windows_x86_64_gnullvm 0.52.6",
"windows_x86_64_msvc 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]] [[package]]
name = "windows-threading" name = "windows-threading"
version = "0.1.0" version = "0.1.0"
@ -5573,6 +5677,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
[[package]] [[package]]
name = "windows_aarch64_msvc" name = "windows_aarch64_msvc"
version = "0.42.2" version = "0.42.2"
@ -5585,6 +5695,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
[[package]]
name = "windows_aarch64_msvc"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
[[package]] [[package]]
name = "windows_i686_gnu" name = "windows_i686_gnu"
version = "0.42.2" version = "0.42.2"
@ -5597,12 +5713,24 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
[[package]]
name = "windows_i686_gnu"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
[[package]] [[package]]
name = "windows_i686_gnullvm" name = "windows_i686_gnullvm"
version = "0.52.6" version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
[[package]]
name = "windows_i686_gnullvm"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
[[package]] [[package]]
name = "windows_i686_msvc" name = "windows_i686_msvc"
version = "0.42.2" version = "0.42.2"
@ -5615,6 +5743,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
[[package]]
name = "windows_i686_msvc"
version = "0.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
[[package]] [[package]]
name = "windows_x86_64_gnu" name = "windows_x86_64_gnu"
version = "0.42.2" version = "0.42.2"
@ -5627,6 +5761,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" 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]] [[package]]
name = "windows_x86_64_gnullvm" name = "windows_x86_64_gnullvm"
version = "0.42.2" version = "0.42.2"
@ -5639,6 +5779,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" 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]] [[package]]
name = "windows_x86_64_msvc" name = "windows_x86_64_msvc"
version = "0.42.2" version = "0.42.2"
@ -5651,6 +5797,12 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" 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]] [[package]]
name = "winnow" name = "winnow"
version = "0.5.40" version = "0.5.40"

View file

@ -24,6 +24,7 @@ lutra-control = { path = "crates/control" }
lutra-mcp = { path = "crates/mcp" } lutra-mcp = { path = "crates/mcp" }
lutra-testkit = { path = "crates/testkit" } lutra-testkit = { path = "crates/testkit" }
ignore = "0.4.33" ignore = "0.4.33"
notify = "8.2.0"
tempfile = "3.27.0" tempfile = "3.27.0"
[workspace.lints.rust] [workspace.lints.rust]

1
NOTICE
View file

@ -19,6 +19,7 @@ Bundled components (planned; update when added):
* tree-sitter and tree-sitter-php — MIT License * tree-sitter and tree-sitter-php — MIT License
* Tauri — MIT OR Apache-2.0 * Tauri — MIT OR Apache-2.0
* unicode-ident and ICU4X crates (via Tauri) — Unicode License v3 (Unicode-3.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: External tools Lutra talks to but does not bundle:
* Phpactor (language server) — MIT License * Phpactor (language server) — MIT License

View file

@ -13,6 +13,7 @@ layer = 2
[dependencies] [dependencies]
ignore.workspace = true ignore.workspace = true
notify.workspace = true
thiserror = "2.0.21" thiserror = "2.0.21"
[dev-dependencies] [dev-dependencies]

View file

@ -33,7 +33,8 @@
//! //!
//! # Watching //! # Watching
//! [`Project::watch`] returns a [`Watcher`] and a channel of [`VfsEvent`]s; //! [`Project::watch`] returns a [`Watcher`] and a channel of [`VfsEvent`]s;
//! see the `watch` module for the polling design and its limits. //! see the `watch` module for the native backend (`notify`), its polling
//! fallback and their limits.
//! //!
//! # File IO //! # File IO
//! [`read_text`] reads up to [`DEFAULT_READ_LIMIT`] bytes and decodes UTF-8 //! [`read_text`] reads up to [`DEFAULT_READ_LIMIT`] bytes and decodes UTF-8
@ -54,4 +55,4 @@ pub use io::{
}; };
pub use project::{Entry, EntryKind, Listing, MAX_CHILDREN, PathStatus, Project, ProjectOptions}; pub use project::{Entry, EntryKind, Listing, MAX_CHILDREN, PathStatus, Project, ProjectOptions};
pub use rules::{EntryRole, GlobalExcludes}; pub use rules::{EntryRole, GlobalExcludes};
pub use watch::{VfsEvent, WatchOptions, Watcher}; pub use watch::{VfsEvent, WatchBackend, WatchOptions, Watcher};

View file

@ -1,19 +1,27 @@
//! Watching the project for changes on disk. //! Watching the project for changes on disk.
//! //!
//! The watcher polls: a background thread re-reads the watched directories //! Two backends sit behind one API:
//! every [`WatchOptions::interval`] (100 ms by default) and compares kind, //! - **Native** (default): operating-system notifications through the
//! size and modification time of each entry with the previous scan. It needs //! `notify` crate (ReadDirectoryChangesW, inotify, FSEvents). A
//! no dependency; native notifications (the `notify` crate) wait on a licence //! notification only marks its directory as dirty; once no notification
//! decision and would sit behind the same API. //! 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.
//! //!
//! Behaviour: //! 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 //! - Only watched directories are scanned, non-recursively. The root is
//! watched from the start; callers add the directories the user expanded //! watched from the start; callers add the directories the user expanded
//! with [`Watcher::watch_dir`]. Directories that are hidden (`.git`), //! with [`Watcher::watch_dir`]. Directories that are hidden (`.git`),
//! ignored or excluded (`node_modules`) are refused, so no events come //! ignored or excluded (`node_modules`) are refused, so no events come
//! from inside them, and `.git` entries are never reported. //! from inside them, and `.git` entries are never reported.
//! - Changes within one interval are coalesced (debounced): several writes //! - Changes within one debounce window are coalesced: several writes give
//! give one [`VfsEvent::Modified`], a file created and deleted again gives //! one [`VfsEvent::Modified`], a file created and deleted again gives
//! nothing. An entry that disappears while one with the same kind, size //! nothing. An entry that disappears while one with the same kind, size
//! and modification time appears in the same scan is reported as //! and modification time appears in the same scan is reported as
//! [`VfsEvent::Renamed`]. //! [`VfsEvent::Renamed`].
@ -22,36 +30,55 @@
//! - A watched directory that disappears stops being watched (its parent //! - A watched directory that disappears stops being watched (its parent
//! reports the removal if watched). If the root cannot be read the watcher //! reports the removal if watched). If the root cannot be read the watcher
//! sends [`VfsEvent::Failed`] and stops: the project keeps working without //! sends [`VfsEvent::Failed`] and stops: the project keeps working without
//! watching. //! 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 //! - A change that keeps size and modification time is not seen; modern file
//! systems record modification times finely enough for this to be rare. //! systems record modification times finely enough for this to be rare.
use std::collections::{BTreeMap, HashMap}; use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::ffi::OsString; use std::ffi::OsString;
use std::fs; use std::fs;
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{self, Receiver, Sender}; use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender};
use std::sync::{Arc, Mutex, MutexGuard, PoisonError}; use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
use std::thread::{self, JoinHandle}; use std::thread::{self, JoinHandle};
use std::time::{Duration, SystemTime}; use std::time::{Duration, Instant, SystemTime};
use notify::{RecommendedWatcher, RecursiveMode, Watcher as _};
use crate::VfsError; use crate::VfsError;
use crate::path::check_relative; use crate::path::check_relative;
use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of}; use crate::project::{EntryKind, MAX_CHILDREN, Project, kind_of};
use crate::rules::{EntryRole, is_hidden}; 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`]. /// Options for [`Project::watch_with`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WatchOptions { pub struct WatchOptions {
/// Time between scans; also the debounce window. /// Debounce window, and the time between scans when polling.
pub interval: Duration, pub interval: Duration,
/// The backend to use.
pub backend: WatchBackend,
} }
impl Default for WatchOptions { impl Default for WatchOptions {
fn default() -> Self { fn default() -> Self {
WatchOptions { WatchOptions {
interval: Duration::from_millis(100), interval: Duration::from_millis(100),
backend: WatchBackend::Auto,
} }
} }
} }
@ -92,7 +119,9 @@ pub enum VfsEvent {
pub struct Watcher { pub struct Watcher {
/// State shared with the thread. /// State shared with the thread.
shared: Arc<Shared>, shared: Arc<Shared>,
/// The polling thread, joined on drop. /// Wakes the thread when the watcher is dropped.
signals: Sender<Signal>,
/// The background thread, joined on drop.
thread: Option<JoinHandle<()>>, thread: Option<JoinHandle<()>>,
} }
@ -103,8 +132,39 @@ struct Shared {
project: Project, project: Project,
/// Set to ask the thread to stop. /// Set to ask the thread to stop.
stop: AtomicBool, stop: AtomicBool,
/// Last scan of every watched directory, keyed by project-relative path. /// Every watched directory, keyed by project-relative path.
dirs: Mutex<BTreeMap<PathBuf, Snapshot>>, dirs: Mutex<BTreeMap<PathBuf, Watched>>,
/// The native watcher, if it started.
native: Mutex<Option<RecommendedWatcher>>,
}
/// 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<PathBuf>),
/// 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<PathBuf>,
/// Rescan every directory.
full: bool,
} }
/// Entries of one directory by name. /// Entries of one directory by name.
@ -142,7 +202,9 @@ impl Project {
} }
/// Starts watching the project root; events arrive on the returned /// Starts watching the project root; events arrive on the returned
/// channel. Changes made after this returns are reported. /// 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 /// # Errors
/// [`VfsError::WatchUnavailable`] if the root cannot be scanned or the /// [`VfsError::WatchUnavailable`] if the root cannot be scanned or the
@ -152,27 +214,40 @@ impl Project {
&self, &self,
options: WatchOptions, options: WatchOptions,
) -> Result<(Watcher, Receiver<VfsEvent>), VfsError> { ) -> Result<(Watcher, Receiver<VfsEvent>), VfsError> {
let root = scan(self.root()).map_err(|err| VfsError::WatchUnavailable { 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()), message: format!("cannot read {}: {err}", self.root().display()),
})?; })?;
let mut dirs = BTreeMap::new(); let mut dirs = BTreeMap::new();
dirs.insert(PathBuf::new(), root); dirs.insert(
PathBuf::new(),
Watched {
snapshot,
native: native.is_some(),
},
);
let shared = Arc::new(Shared { let shared = Arc::new(Shared {
project: self.clone(), project: self.clone(),
stop: AtomicBool::new(false), stop: AtomicBool::new(false),
dirs: Mutex::new(dirs), dirs: Mutex::new(dirs),
native: Mutex::new(native),
}); });
let (sender, receiver) = mpsc::channel(); let (sender, receiver) = mpsc::channel();
let thread_shared = Arc::clone(&shared); let thread_shared = Arc::clone(&shared);
let thread = thread::Builder::new() let thread = thread::Builder::new()
.name("lutra-vfs-watch".into()) .name("lutra-vfs-watch".into())
.spawn(move || run(&thread_shared, &sender, options.interval)) .spawn(move || run(&thread_shared, &signal_receiver, &sender, options.interval))
.map_err(|err| VfsError::WatchUnavailable { .map_err(|err| VfsError::WatchUnavailable {
message: format!("cannot start the watcher thread: {err}"), message: format!("cannot start the watcher thread: {err}"),
})?; })?;
Ok(( Ok((
Watcher { Watcher {
shared, shared,
signals,
thread: Some(thread), thread: Some(thread),
}, },
receiver, receiver,
@ -180,10 +255,28 @@ impl Project {
} }
} }
/// 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<Signal>) -> Option<RecommendedWatcher> {
let handler = move |result: notify::Result<notify::Event>| {
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 { impl Watcher {
/// Starts watching the directory `dir` (project-relative). Returns /// Starts watching the directory `dir` (project-relative). Returns
/// `false` without watching if the directory is hidden, ignored or /// `false` without watching if the directory is hidden, ignored or
/// excluded; watching an already watched directory is a no-op. /// excluded; watching an already watched directory is a no-op. If the
/// native watcher refuses the directory, it is polled instead.
/// ///
/// # Errors /// # Errors
/// [`VfsError::OutsideProject`] for an escaping path, [`VfsError::NotFound`] /// [`VfsError::OutsideProject`] for an escaping path, [`VfsError::NotFound`]
@ -198,16 +291,35 @@ impl Watcher {
return Ok(true); return Ok(true);
} }
let abs = self.shared.project.root().join(&dir); let abs = self.shared.project.root().join(&dir);
let snapshot = scan(&abs).map_err(|err| VfsError::io(&abs, err))?; let native = self
self.shared.lock().entry(dir).or_insert(snapshot); .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) Ok(true)
} }
/// Stops watching the directory `dir` (project-relative). Unknown /// Stops watching the directory `dir` (project-relative). Unknown
/// directories are ignored. /// directories are ignored.
pub fn unwatch_dir(&self, dir: impl AsRef<Path>) { pub fn unwatch_dir(&self, dir: impl AsRef<Path>) {
if let Ok(dir) = check_relative(dir.as_ref()) { let Ok(dir) = check_relative(dir.as_ref()) else {
self.shared.lock().remove(&dir); 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));
} }
} }
@ -215,37 +327,101 @@ impl Watcher {
pub fn watched_dirs(&self) -> Vec<PathBuf> { pub fn watched_dirs(&self) -> Vec<PathBuf> {
self.shared.lock().keys().cloned().collect() 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 { impl Drop for Watcher {
/// Stops and joins the polling thread. A panic inside the thread is not /// Stops the native watcher, then stops and joins the thread. A failed
/// propagated: the watcher is going away and has nothing left to report. /// 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) { fn drop(&mut self) {
self.shared.stop.store(true, Ordering::SeqCst); 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() { if let Some(thread) = self.thread.take() {
thread.thread().unpark();
let _thread_result = thread.join(); let _thread_result = thread.join();
} }
} }
} }
impl Shared { impl Shared {
/// Locks the snapshots. A poisoned lock is recovered: snapshots are only /// Locks the watched directories. A poisoned lock is recovered:
/// replaced whole, so they are consistent even after a panic. /// entries are only replaced whole, so they are consistent even after a
fn lock(&self) -> MutexGuard<'_, BTreeMap<PathBuf, Snapshot>> { /// panic.
fn lock(&self) -> MutexGuard<'_, BTreeMap<PathBuf, Watched>> {
self.dirs.lock().unwrap_or_else(PoisonError::into_inner) 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<RecommendedWatcher>> {
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);
}
}
} }
/// Body of the polling thread: scan, diff, send, until stopped, until the impl Work {
/// receiver is dropped or until the root fails. /// Records a signal; `false` for [`Signal::Stop`].
fn run(shared: &Shared, sender: &Sender<VfsEvent>, interval: Duration) { 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<Signal>, sender: &Sender<VfsEvent>, interval: Duration) {
loop { loop {
thread::park_timeout(interval); 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) { if shared.stop.load(Ordering::SeqCst) {
return; return;
} }
let (events, failed) = poll(shared); let (events, failed) = poll(shared, &work);
for event in events { for event in events {
if sender.send(event).is_err() { if sender.send(event).is_err() {
return; return;
@ -257,36 +433,83 @@ fn run(shared: &Shared, sender: &Sender<VfsEvent>, interval: Duration) {
} }
} }
/// Rescans every watched directory and returns the events, plus whether /// Collects further signals until none arrives for `interval`, or for at
/// watching failed for good. /// most [`MAX_DEBOUNCE_INTERVALS`] intervals. Returns `false` if the thread
fn poll(shared: &Shared) -> (Vec<VfsEvent>, bool) { /// must stop.
fn debounce(
shared: &Shared,
signals: &Receiver<Signal>,
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<VfsEvent>, bool) {
let root = shared.project.root(); let root = shared.project.root();
let mut dirs = shared.lock(); 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 changes = Changes::default();
let mut gone = Vec::new(); let mut gone = Vec::new();
let mut root_error = None; if root_error.is_none() {
for (dir, old) in dirs.iter_mut() { for (dir, watched) in dirs.iter_mut() {
if watched.native && !work.full && !work.dirty.contains(dir) {
continue;
}
match scan(&root.join(dir)) { match scan(&root.join(dir)) {
Ok(new) => { Ok(new) => {
diff(dir, old, &new, &mut changes); diff(dir, &watched.snapshot, &new, &mut changes);
*old = new; watched.snapshot = new;
} }
Err(err) if dir.as_os_str().is_empty() => { Err(err) if dir.as_os_str().is_empty() => {
root_error = Some(err); root_error = Some(err.to_string());
break; break;
} }
Err(_) => gone.push(dir.clone()), Err(_) => gone.push((dir.clone(), watched.native)),
}
} }
} }
if let Some(err) = root_error { if let Some(err) = root_error {
dirs.clear(); dirs.clear();
drop(dirs);
let native = shared.lock_native().take();
drop(native);
let failure = VfsError::WatchUnavailable { let failure = VfsError::WatchUnavailable {
message: format!("cannot read {}: {err}", root.display()), message: format!("cannot read {}: {err}", root.display()),
}; };
return (vec![VfsEvent::Failed(failure)], true); return (vec![VfsEvent::Failed(failure)], true);
} }
for dir in gone { for (dir, _) in &gone {
dirs.remove(&dir); dirs.remove(dir);
}
drop(dirs);
for (dir, native) in gone {
if native {
shared.unwatch_native(&root.join(dir));
}
} }
(pair_renames(changes), false) (pair_renames(changes), false)
} }

View file

@ -1,4 +1,5 @@
//! The polling watcher. Every wait is bounded by a timeout on the channel. //! The watcher, run once per backend (native and polling). Every wait is
//! bounded by a timeout on the channel.
#![allow( #![allow(
clippy::unwrap_used, clippy::unwrap_used,
@ -15,7 +16,7 @@ use std::sync::mpsc::{Receiver, RecvTimeoutError};
use std::time::{Duration, Instant}; use std::time::{Duration, Instant};
use common::{open, tree}; use common::{open, tree};
use lutra_vfs::{EntryKind, VfsEvent, WatchOptions}; use lutra_vfs::{EntryKind, Project, VfsEvent, WatchBackend, WatchOptions, Watcher};
const TIMEOUT: Duration = Duration::from_secs(10); const TIMEOUT: Duration = Duration::from_secs(10);
@ -35,15 +36,53 @@ fn wait_for(rx: &Receiver<VfsEvent>, want: impl Fn(&VfsEvent) -> bool) -> Vec<Vf
} }
} }
/// 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<VfsEvent>) {
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<VfsEvent>) {
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 + '_ { fn is_created(path: &Path) -> impl Fn(&VfsEvent) -> bool + '_ {
move |e| matches!(e, VfsEvent::Created { path: p, .. } if p == path) move |e| matches!(e, VfsEvent::Created { path: p, .. } if p == path)
} }
#[test] fn reports_create_modify_rename_and_delete(backend: WatchBackend) {
fn reports_create_modify_rename_and_delete() {
let dir = tree(&[("keep.php", "")]); let dir = tree(&[("keep.php", "")]);
let project = open(dir.path()); let project = open(dir.path());
let (_watcher, rx) = project.watch().unwrap(); let (_watcher, rx) = watch(&project, backend);
fs::write(dir.path().join("new.php"), "a").unwrap(); fs::write(dir.path().join("new.php"), "a").unwrap();
wait_for(&rx, is_created(Path::new("new.php"))); wait_for(&rx, is_created(Path::new("new.php")));
@ -69,11 +108,10 @@ fn reports_create_modify_rename_and_delete() {
); );
} }
#[test] fn reports_directories_and_watched_subdirectories(backend: WatchBackend) {
fn reports_directories_and_watched_subdirectories() {
let dir = tree(&[]); let dir = tree(&[]);
let project = open(dir.path()); let project = open(dir.path());
let (watcher, rx) = project.watch().unwrap(); let (watcher, rx) = watch(&project, backend);
fs::create_dir(dir.path().join("src")).unwrap(); fs::create_dir(dir.path().join("src")).unwrap();
wait_for(&rx, |e| { wait_for(&rx, |e| {
*e == VfsEvent::Created { *e == VfsEvent::Created {
@ -93,8 +131,7 @@ fn reports_directories_and_watched_subdirectories() {
assert_eq!(watcher.watched_dirs(), [PathBuf::new()]); assert_eq!(watcher.watched_dirs(), [PathBuf::new()]);
} }
#[test] fn ignored_hidden_and_excluded_directories_are_not_watched(backend: WatchBackend) {
fn ignored_hidden_and_excluded_directories_are_not_watched() {
let dir = tree(&[ let dir = tree(&[
(".gitignore", "target/\n"), (".gitignore", "target/\n"),
("target/", ""), ("target/", ""),
@ -103,7 +140,7 @@ fn ignored_hidden_and_excluded_directories_are_not_watched() {
("src/", ""), ("src/", ""),
]); ]);
let project = open(dir.path()); let project = open(dir.path());
let (watcher, rx) = project.watch().unwrap(); let (watcher, rx) = watch(&project, backend);
assert!(!watcher.watch_dir("target").unwrap()); assert!(!watcher.watch_dir("target").unwrap());
assert!(!watcher.watch_dir("node_modules").unwrap()); assert!(!watcher.watch_dir("node_modules").unwrap());
assert!(!watcher.watch_dir(".git").unwrap()); assert!(!watcher.watch_dir(".git").unwrap());
@ -124,31 +161,26 @@ fn ignored_hidden_and_excluded_directories_are_not_watched() {
} }
} }
#[test] fn changes_within_one_interval_are_coalesced(backend: WatchBackend) {
fn changes_within_one_interval_are_coalesced() {
let dir = tree(&[]); let dir = tree(&[]);
let project = open(dir.path()); let project = open(dir.path());
let (_watcher, rx) = project let (_watcher, rx) = start(&project, backend, Duration::from_secs(2));
.watch_with(WatchOptions {
interval: Duration::from_secs(2),
})
.unwrap();
let start = Instant::now(); let start = Instant::now();
fs::write(dir.path().join("flash.tmp"), "x").unwrap(); fs::write(dir.path().join("flash.tmp"), "x").unwrap();
fs::remove_file(dir.path().join("flash.tmp")).unwrap(); fs::remove_file(dir.path().join("flash.tmp")).unwrap();
fs::write(dir.path().join("marker.php"), "x").unwrap(); fs::write(dir.path().join("marker.php"), "x").unwrap();
let before = wait_for(&rx, is_created(Path::new("marker.php"))); let before = wait_for(&rx, is_created(Path::new("marker.php")));
if start.elapsed() < Duration::from_secs(2) { 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:?}"); assert!(before.is_empty(), "flash.tmp leaked: {before:?}");
} }
} }
#[test] fn losing_the_root_degrades_to_an_error_event(backend: WatchBackend) {
fn losing_the_root_degrades_to_an_error_event() {
let parent = tree(&[("project/a.php", "")]); let parent = tree(&[("project/a.php", "")]);
let root = parent.path().join("project"); let root = parent.path().join("project");
let project = open(&root); let project = open(&root);
let (_watcher, rx) = project.watch().unwrap(); let (_watcher, rx) = watch(&project, backend);
fs::remove_dir_all(&root).unwrap(); fs::remove_dir_all(&root).unwrap();
wait_for(&rx, |e| matches!(e, VfsEvent::Failed(_))); wait_for(&rx, |e| matches!(e, VfsEvent::Failed(_)));
let deadline = Instant::now() + TIMEOUT; let deadline = Instant::now() + TIMEOUT;
@ -161,11 +193,10 @@ fn losing_the_root_degrades_to_an_error_event() {
} }
} }
#[test] fn dropping_the_watcher_closes_the_channel(backend: WatchBackend) {
fn dropping_the_watcher_closes_the_channel() {
let dir = tree(&[]); let dir = tree(&[]);
let project = open(dir.path()); let project = open(dir.path());
let (watcher, rx) = project.watch().unwrap(); let (watcher, rx) = watch(&project, backend);
drop(watcher); drop(watcher);
assert_eq!( assert_eq!(
rx.recv_timeout(TIMEOUT), rx.recv_timeout(TIMEOUT),

View file

@ -24,5 +24,11 @@ allow = [
"Unicode-3.0", "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] [licenses.private]
ignore = true ignore = true

View file

@ -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) | | 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 | | G2 | Editor core: buffers, undo, multi-caret, save, recovery journal | 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 | | 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 | | 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 | | 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 | | G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor | M3 | ~45 h |
@ -29,14 +29,11 @@ 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. - `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. - `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 ## Revision history
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 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 | 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-14 | minor | G1 closed; estimates for G2–G16; M0 follow-ups |
| 2026-10-13 | major | Initial gap list | | 2026-10-13 | major | Initial gap list |

View file

@ -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 | | Area | Weight | Score | Missing | Hours (one agent) | Evidence |
|---|---:|---:|---|---:|---| |---|---:|---:|---|---:|---|
| Editor core | 12 | 0% | everything | ~120 (est.) | — | | Editor core | 12 | 0% | everything | ~120 (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`) | | 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.) | — | | Navigation | 10 | 0% | everything | ~120 (est.) | — |
| Search and replace | 6 | 0% | everything | ~80 (est.) | — | | Search and replace | 6 | 0% | everything | ~80 (est.) | — |
| Code completion | 10 | 0% | everything | ~250 (est.) | — | | Code completion | 10 | 0% | everything | ~250 (est.) | — |
@ -52,6 +52,7 @@ No PHP feature. The foundation, verified on Windows 11:
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 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 | Project view evidence: `lutra-vfs` (M1.2), score unchanged |
| 2026-10-14 | minor | Hours per area, weights reviewed, M0 evidence | | 2026-10-14 | minor | Hours per area, weights reviewed, M0 evidence |
| 2026-10-13 | major | Baseline | | 2026-10-13 | major | Baseline |