Lutra/crates/vfs/src/project.rs
danny 5d49b57b9c 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>
2026-10-14 19:24:02 +02:00

256 lines
8.8 KiB
Rust

//! 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<Globals>,
}
/// 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<Entry>,
/// 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<Path>) -> Result<Self, VfsError> {
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<Path>, options: ProjectOptions) -> Result<Self, VfsError> {
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<Path>) -> Result<PathBuf, VfsError> {
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<Path>) -> Option<PathBuf> {
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<Path>) -> Result<Listing, VfsError> {
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<Path>) -> Result<PathStatus, VfsError> {
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))
}