Lutra/crates/vfs/src/lib.rs
danny 3f190a635e 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>
2026-10-14 19:43:15 +02:00

58 lines
2.4 KiB
Rust

//! Virtual file system for Lutra (layer L2).
//!
//! Models an open project: its root, lazy directory listing, ignore rules,
//! file watching and text encodings. File contents and names read here are
//! untrusted input: sizes and counts are capped and nothing panics on odd
//! data.
//!
//! # Projects and listing
//! [`Project::open`] canonicalises the root (on Windows without the `\\?\`
//! prefix where that is safe) and reads nothing below it.
//! [`Project::children`] lists one directory on demand, sorted directories
//! first, then by case-insensitive name, each [`Entry`] with its kind, an
//! `ignored` flag and an [`EntryRole`]. Paths in the API are relative to the
//! project root; `..` and absolute paths are rejected.
//!
//! # Ignore rules
//! An entry is `ignored` when `.gitignore`, `.ignore`, `.git/info/exclude`
//! or the global git excludes file match it or one of its ancestors (see the
//! `rules` module for precedence). Rules apply whether or not the folder is a
//! git repository, and match case-sensitively. Ignored entries are still
//! listed; the UI dims them.
//!
//! Lutra's defaults, applied on top of the ignore files:
//! - `.git` (directory or file) at any depth is hidden: never listed,
//! watched or reported.
//! - `vendor/` directly under the root (Composer's default `vendor-dir`) is
//! [`EntryRole::Library`]: listed, not ignored, treated as third-party code.
//! - `node_modules/` at any depth is [`EntryRole::Excluded`]: listed, but
//! not watched or indexed.
//!
//! Roles are inherited: everything below `vendor/` is a library, everything
//! below `node_modules/` excluded.
//!
//! # Watching
//! [`Project::watch`] returns a [`Watcher`] and a channel of [`VfsEvent`]s;
//! see the `watch` module for the native backend (`notify`), its polling
//! fallback and their limits.
//!
//! # File IO
//! [`read_text`] reads up to [`DEFAULT_READ_LIMIT`] bytes and decodes UTF-8
//! with an optional BOM; [`write_atomic`] and [`write_text`] replace a file
//! through a temporary file and a rename, keeping its permissions.
mod error;
mod io;
mod path;
mod project;
mod rules;
mod watch;
pub use error::VfsError;
pub use io::{
DEFAULT_READ_LIMIT, TextFile, decode, read_bytes, read_text, read_text_with_limit,
write_atomic, write_text,
};
pub use project::{Entry, EntryKind, Listing, MAX_CHILDREN, PathStatus, Project, ProjectOptions};
pub use rules::{EntryRole, GlobalExcludes};
pub use watch::{VfsEvent, WatchBackend, WatchOptions, Watcher};