Lutra/crates/engine/src/workspace.rs
danny 13e7b0aa12 M4.1: Git backend through the installed git
New crate lutra-vcs (L3): a safe git runner (argument arrays, no prompts,
GIT_OPTIONAL_LOCKS=0 for reads, timeouts 30 s / 120 s for hooks, output
caps, one spawn function for H1's kill-on-close helper), porcelain v2 / -z
parsers (property-tested), Repo operations (status, stage, unstage before
the first commit, commit and amend, show at HEAD/index, branches, checkout
with remote tracking, branch creation checked by check-ref-format) and a
.git poll (RepoWatch).

Engine: git.status, git.stage, git.unstage, git.commit, git.show,
git.branches, git.checkout, git.createBranch on pending outcomes, off the
engine lock; gitChanged after changes and debounced 300 ms on .git or
project changes; setting git.executable (section Git).

Tests against real temp repositories, engine tests through run_waiting,
docs (architecture, gaps G8, Git parity row, roadmap M4 row).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 16:52:29 +01:00

377 lines
13 KiB
Rust

//! The open project: the VFS project, its watcher, and the translation of
//! changes on disk into engine events and buffer reloads.
//!
//! # Watched directories
//! The VFS watcher is non-recursive: the root is watched from the start and
//! [`Workspace::touch_dir`] adds each directory whose children a client
//! lists. To keep the cost bounded on huge trees (a deep `vendor/`), at most
//! [`MAX_WATCHED_DIRS_NATIVE`] directories besides the root are watched with
//! native notifications, and [`MAX_WATCHED_DIRS_POLLING`] when the watcher
//! fell back to polling, where every watched directory is rescanned each
//! interval. When the limit is reached the directory listed least recently
//! is unwatched; listing it again watches it again. Changes inside an
//! unwatched directory are not reported until then.
//!
//! The parent directory of every open buffer is pinned by
//! [`sync_buffer_dirs`]: it is watched even if no client listed it, so
//! [`Event::FileChangedOnDisk`] and reloads arrive for files in folders the
//! tree never expanded. Pinned directories count against the limit but are
//! never unwatched while a buffer in them is open, so with more pinned
//! directories than the limit allows, the watched set exceeds it. A
//! directory the watcher refuses (hidden, ignored or excluded) stays
//! unwatched even when pinned.
use std::collections::{BTreeSet, VecDeque};
use std::path::{Path, PathBuf};
use std::sync::mpsc::{Receiver, TryRecvError};
use lutra_text::Buffer;
use lutra_vfs::{Project, VfsError, VfsEvent, Watcher};
use crate::buffers::BufferId;
use crate::{EngineError, Event, State};
/// Directories watched besides the root with native notifications.
pub const MAX_WATCHED_DIRS_NATIVE: usize = 256;
/// Directories watched besides the root when polling.
pub const MAX_WATCHED_DIRS_POLLING: usize = 32;
/// Most VFS events handled by one pump; the rest wait for the next one.
pub const MAX_EVENTS_PER_PUMP: usize = 10_000;
/// An open project.
#[derive(Debug)]
pub struct Workspace {
/// The VFS project.
pub project: Project,
/// The watcher, `None` if watching is unavailable or failed.
watcher: Option<Watcher>,
/// Changes on disk from the watcher.
events: Option<Receiver<VfsEvent>>,
/// Directories watched besides the root, least recently listed first.
watched: VecDeque<PathBuf>,
/// Parent directories of open buffers; never unwatched while pinned.
pinned: BTreeSet<PathBuf>,
}
impl Workspace {
/// Opens the folder at `path` and starts watching it. A watcher that
/// cannot start is not an error: the workspace works without it and the
/// returned events contain [`Event::WatchFailed`].
///
/// # Errors
/// [`EngineError::Failed`] if the folder cannot be opened.
pub fn open(path: &Path) -> Result<(Self, Vec<Event>), EngineError> {
let project = Project::open(path).map_err(vfs_error)?;
let root = project.root().to_path_buf();
let mut events = vec![Event::ProjectOpened {
root: root.to_string_lossy().into_owned(),
name: root
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_else(|| root.to_string_lossy().into_owned()),
}];
let (watcher, receiver) = match project.watch() {
Ok((watcher, receiver)) => (Some(watcher), Some(receiver)),
Err(e) => {
events.push(Event::WatchFailed {
message: e.to_string(),
});
(None, None)
}
};
Ok((
Self {
project,
watcher,
events: receiver,
watched: VecDeque::new(),
pinned: BTreeSet::new(),
},
events,
))
}
/// Records that a client listed `dir` and watches it, unwatching the
/// least recently listed unpinned directory if the limit is reached.
/// Watching is best effort: a directory the watcher refuses or cannot
/// read is simply not watched, because listing it worked and that is
/// what the caller asked for.
pub fn touch_dir(&mut self, dir: &Path) {
if self.watch(dir) {
self.evict();
}
}
/// Makes `dirs` the pinned directories: each is watched and kept watched
/// until a later call leaves it out, after which it ages out like a
/// listed directory. The root (`""`) is always watched and is skipped.
pub fn pin_dirs(&mut self, dirs: BTreeSet<PathBuf>) {
if self.watcher.is_none() || dirs == self.pinned {
return;
}
for dir in &dirs {
if !self.pinned.contains(dir) {
self.watch(dir);
}
}
self.pinned = dirs;
self.evict();
}
/// Watches `dir` and moves it to the most recently used end. Returns
/// whether it is watched now.
fn watch(&mut self, dir: &Path) -> bool {
let Some(watcher) = &self.watcher else {
return false;
};
if dir.as_os_str().is_empty() {
return false;
}
if let Some(at) = self.watched.iter().position(|d| d == dir) {
if let Some(d) = self.watched.remove(at) {
self.watched.push_back(d);
}
return true;
}
if !matches!(watcher.watch_dir(dir), Ok(true)) {
return false;
}
self.watched.push_back(dir.to_path_buf());
true
}
/// Unwatches the least recently used unpinned directories until the
/// watched set fits the limit or only pinned directories remain.
fn evict(&mut self) {
let limit = self.watch_limit();
let Some(watcher) = &self.watcher else {
return;
};
while self.watched.len() > limit {
let Some(at) = self.watched.iter().position(|d| !self.pinned.contains(d)) else {
return;
};
if let Some(old) = self.watched.remove(at) {
watcher.unwatch_dir(&old);
}
}
}
/// How many directories besides the root may be watched with the
/// current backend; 0 without a watcher.
pub fn watch_limit(&self) -> usize {
match &self.watcher {
Some(w) if w.is_native() => MAX_WATCHED_DIRS_NATIVE,
Some(_) => MAX_WATCHED_DIRS_POLLING,
None => 0,
}
}
/// Directories watched besides the root, least recently listed first.
pub fn watched_dirs(&self) -> Vec<PathBuf> {
self.watched.iter().cloned().collect()
}
/// The pinned directories (parents of open buffers), sorted.
pub fn pinned_dirs(&self) -> Vec<PathBuf> {
self.pinned.iter().cloned().collect()
}
/// Whether the project is watched.
pub fn is_watching(&self) -> bool {
self.watcher.is_some()
}
/// Takes up to [`MAX_EVENTS_PER_PUMP`] pending changes from the watcher.
/// A failed or disconnected watcher is dropped and reported once.
fn drain(&mut self) -> (Vec<VfsEvent>, Option<String>) {
let mut out = Vec::new();
let mut failure = None;
let Some(receiver) = &self.events else {
return (out, None);
};
while out.len() < MAX_EVENTS_PER_PUMP {
match receiver.try_recv() {
Ok(VfsEvent::Failed(e)) => {
failure = Some(e.to_string());
break;
}
Ok(event) => out.push(event),
Err(TryRecvError::Empty) => break,
Err(TryRecvError::Disconnected) => {
failure = Some("the file watcher stopped".to_string());
break;
}
}
}
if failure.is_some() {
self.watcher = None;
self.events = None;
self.watched.clear();
self.pinned.clear();
}
(out, failure)
}
}
/// Pins the parent directory of every open buffer in the workspace watcher
/// (see the module docs). The engine calls it after every command, so
/// opening, restoring and closing buffers keep the pins current.
pub fn sync_buffer_dirs(state: &mut State) {
let Some(workspace) = state.project.as_mut() else {
return;
};
let dirs: BTreeSet<PathBuf> = state
.buffers
.ids()
.into_iter()
.filter_map(|id| state.buffers.get(id))
.filter_map(|b| b.path.parent().map(Path::to_path_buf))
.filter(|d| !d.as_os_str().is_empty())
.collect();
workspace.pin_dirs(dirs);
}
/// Applies pending changes on disk to the state: hands them to the symbol
/// index ([`crate::cmd::goto::note_disk_changes`]), queues
/// [`Event::TreeChanged`] for affected directories, reloads clean buffers
/// whose file changed, and queues [`Event::FileChangedOnDisk`] for dirty
/// buffers and for buffers whose file disappeared.
pub fn pump(state: &mut State) {
let Some(workspace) = state.project.as_mut() else {
return;
};
let (changes, failure) = workspace.drain();
let root = workspace.project.root().to_path_buf();
crate::cmd::goto::note_disk_changes(state, &changes);
crate::cmd::git::note_disk_changes(state, &changes);
let mut dirs: Vec<PathBuf> = Vec::new();
let mut add_dir = |path: &Path| {
let dir = path.parent().map(Path::to_path_buf).unwrap_or_default();
if !dirs.contains(&dir) {
dirs.push(dir);
}
};
let mut modified = Vec::new();
let mut gone = Vec::new();
for change in changes {
match change {
VfsEvent::Created { path, .. } => add_dir(&path),
VfsEvent::Removed { path } => {
add_dir(&path);
gone.push(path);
}
VfsEvent::Renamed { from, to } => {
add_dir(&from);
add_dir(&to);
gone.push(from);
}
VfsEvent::Modified { path } => modified.push(path),
VfsEvent::Failed(_) => {}
}
}
for dir in dirs {
state.emit(Event::TreeChanged {
dir: path_string(&dir),
});
}
for path in gone {
if let Some(id) = state.buffers.find(&path) {
state.buffers.mark_conflict(id);
state.emit(Event::FileChangedOnDisk {
path: path_string(&path),
id,
removed: true,
});
}
}
for path in modified {
if let Some(id) = state.buffers.find(&path) {
reload(state, id, &root.join(&path));
}
}
if let Some(message) = failure {
state.emit(Event::WatchFailed { message });
}
}
/// Brings buffer `id` in line with its file after the file changed: a clean
/// buffer takes the new text (unless it already matches, as after our own
/// save), a dirty one keeps its text and the client is told, and the buffer
/// is marked as in conflict ([`crate::buffers::Buffers::mark_conflict`]).
/// A dirty buffer whose file holds exactly what Lutra last wrote is left
/// alone: that is our own save reported after the user typed again (an
/// autosave followed by a keystroke). A file that cannot be read is reported
/// like a removed one.
fn reload(state: &mut State, id: BufferId, abs: &Path) {
let Some(open) = state.buffers.get(id) else {
return;
};
let path = path_string(&open.path);
let dirty = open.dirty();
let file = match lutra_vfs::read_text(abs) {
Ok(file) => file,
Err(_) => {
state.buffers.mark_conflict(id);
state.emit(Event::FileChangedOnDisk {
path,
id,
removed: true,
});
return;
}
};
if dirty {
if state.buffers.is_own_write(
id,
&crate::journal::hex_hash(file.text.as_bytes()),
file.bom,
) {
return;
}
state.buffers.mark_conflict(id);
state.emit(Event::FileChangedOnDisk {
path,
id,
removed: false,
});
return;
}
let Some(open) = state.buffers.get(id) else {
return;
};
if file.text == open.buffer.save_text() && file.bom == open.bom {
state.buffers.clear_conflict(id);
return;
}
let Some(open) = state.buffers.get_mut(id) else {
return;
};
let hash = crate::journal::hex_hash(file.text.as_bytes());
open.buffer = Buffer::new(&file.text);
open.bom = file.bom;
open.version = open.version.saturating_add(1);
open.saved_version = open.version;
let version = open.version;
state.buffers.clear_conflict(id);
state.buffers.note_written(id, hash, file.bom);
state.emit(Event::BufferChanged { id, version });
}
/// A project-relative path as sent to clients: `/` separators, `""` for the
/// root.
pub fn path_string(path: &Path) -> String {
let text = path.to_string_lossy();
if std::path::MAIN_SEPARATOR == '/' {
text.into_owned()
} else {
text.replace(std::path::MAIN_SEPARATOR, "/")
}
}
/// Converts a VFS error into an engine error.
pub fn vfs_error(error: VfsError) -> EngineError {
EngineError::Failed(error.to_string())
}