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 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-14 19:23:54 +02:00
parent faadb05eb3
commit 5d49b57b9c
16 changed files with 2058 additions and 4 deletions

View file

@ -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};