ailloli_ui_widgets/files/store.rs
1//! Append-only retained file-tree arena with cached visible-row projection.
2
3use std::collections::HashMap;
4
5use ailloli_ui_fs::{FileEntry, FileMetadata, FileProvider, FileUri};
6
7use super::model::FileExplorerNode;
8use super::tree::{
9 error_placeholder, file_uri_ancestors_between, large_directory_placeholder,
10 loading_placeholder, should_include_file_entry, sort_file_entries,
11 symlink_policy_allows_descend, truncate_entries, ChildLoadReason, FileTreeOptions,
12};
13
14/// Store-local index into [`FileTreeStore::nodes`].
15///
16/// IDs are append-only and stable for the lifetime of a store, but rebuilding a
17/// directory appends new nodes and can leave old detached nodes in the arena.
18/// Constructing an arbitrary index is allowed; methods that index directly may
19/// panic when it is out of bounds.
20///
21/// # Examples
22///
23/// ```
24/// use ailloli_ui_widgets::files::FileTreeNodeId;
25/// assert_eq!(FileTreeNodeId(4).0, 4);
26/// ```
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
28pub struct FileTreeNodeId(pub usize);
29
30/// Retained directory-listing state for one node.
31///
32/// # Examples
33///
34/// ```
35/// use ailloli_ui_widgets::files::DirLoadState;
36/// let state = DirLoadState::Loaded { revision: 2, entry_count: 4 };
37/// assert!(matches!(state, DirLoadState::Loaded { entry_count: 4, .. }));
38/// ```
39#[derive(Debug, Clone, PartialEq, Eq)]
40pub enum DirLoadState {
41 /// Metadata is leaf-like or symlink traversal is disallowed.
42 NotDirectory,
43 /// Loadable directory whose children have not yet been requested.
44 Unloaded,
45 /// Synchronous/asynchronous owner has marked a request in progress.
46 Loading,
47 /// A listing was accepted without truncation.
48 Loaded {
49 /// Store revision allocated when children were merged.
50 revision: u64,
51 /// Retained child count after filtering and sorting.
52 entry_count: usize,
53 },
54 /// The most recent canonicalization or listing attempt failed.
55 Error {
56 /// Display-ready provider error text.
57 message: String,
58 },
59 /// Children hold a truncated prefix and need a large-directory placeholder.
60 Dirty,
61}
62
63/// One arena record in a [`FileTreeStore`].
64///
65/// # Examples
66///
67/// ```
68/// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
69/// use ailloli_ui_widgets::files::FileTreeStore;
70/// let root = FileEntry::new(FileUri::parse("file:///repo")?, FileMetadata::new(FileKind::Directory));
71/// let store = FileTreeStore::new(root, None);
72/// assert_eq!((store.nodes()[0].id.0, store.nodes()[0].depth), (0, 0));
73/// # Ok::<(), ailloli_ui_fs::FileError>(())
74/// ```
75#[derive(Debug, Clone, PartialEq, Eq)]
76pub struct FileTreeNode {
77 /// Stable arena identifier.
78 pub id: FileTreeNodeId,
79 /// Parent identifier, or `None` for the root/detached records.
80 pub parent: Option<FileTreeNodeId>,
81 /// Current URI, name, and metadata snapshot.
82 pub entry: FileEntry,
83 /// Lazily cached provider canonical URI used for cycle detection.
84 pub canonical_uri: Option<FileUri>,
85 /// Ordered identifiers of currently attached children.
86 pub children: Vec<FileTreeNodeId>,
87 /// Current directory loading state.
88 pub load_state: DirLoadState,
89 /// Zero-based depth captured when the node was appended.
90 pub depth: usize,
91}
92
93/// Retained arena, URI index, expansion state, and visible-row cache.
94///
95/// Revisions use saturating addition and therefore never wrap. Provider reads
96/// are synchronous. Replacing children removes their URI indexes and expansion
97/// state but retains detached arena records so existing IDs never move.
98///
99/// # Examples
100///
101/// ```
102/// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
103/// use ailloli_ui_widgets::files::FileTreeStore;
104/// let root = FileEntry::new(FileUri::parse("file:///repo")?, FileMetadata::new(FileKind::Directory));
105/// let store = FileTreeStore::new(root, None);
106/// assert_eq!((store.revision(), store.nodes().len()), (0, 1));
107/// # Ok::<(), ailloli_ui_fs::FileError>(())
108/// ```
109#[derive(Debug, Clone)]
110pub struct FileTreeStore {
111 /// Stable root node identity.
112 root: FileTreeNodeId,
113 /// Dense node storage indexed by [`FileTreeNodeId`].
114 nodes: Vec<FileTreeNode>,
115 /// Canonical URI-to-node lookup table.
116 uri_index: HashMap<FileUri, FileTreeNodeId>,
117 /// Expanded directory identities in deterministic presentation order.
118 expanded: Vec<FileTreeNodeId>,
119 /// Selected canonical URI, retained across compatible rebuilds.
120 selected: Option<FileUri>,
121 /// Cached flattened preorder rows for the current expansion state.
122 visible_rows: Vec<FileTreeNodeId>,
123 /// Whether [`Self::visible_rows`] must be recomputed before reading.
124 visible_dirty: bool,
125 /// Wrapping model revision incremented by observable mutations.
126 revision: u64,
127}
128
129impl FileTreeStore {
130 /// Creates a revision-zero store whose root has ID zero and is expanded.
131 ///
132 /// `selected` is stored without checking ancestry or existence. Initial root
133 /// load state follows its metadata under default symlink policy. The visible
134 /// cache is built immediately and is therefore initially clean.
135 ///
136 /// # Examples
137 ///
138 /// ```
139 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
140 /// use ailloli_ui_widgets::files::{FileTreeNodeId, FileTreeStore};
141 /// let root = FileEntry::new(FileUri::parse("file:///repo")?, FileMetadata::new(FileKind::Directory));
142 /// let mut store = FileTreeStore::new(root, None);
143 /// assert_eq!(store.visible_rows(), &[FileTreeNodeId(0)]);
144 /// assert!(!store.visible_dirty());
145 /// # Ok::<(), ailloli_ui_fs::FileError>(())
146 /// ```
147 pub fn new(root: FileEntry, selected: Option<FileUri>) -> Self {
148 let root_id = FileTreeNodeId(0);
149 let load_state = dir_load_state_for_metadata(&root.metadata, FileTreeOptions::default());
150 let mut uri_index = HashMap::new();
151 uri_index.insert(root.uri.clone(), root_id);
152 let mut store = Self {
153 root: root_id,
154 nodes: vec![FileTreeNode {
155 id: root_id,
156 parent: None,
157 entry: root,
158 canonical_uri: None,
159 children: Vec::new(),
160 load_state,
161 depth: 0,
162 }],
163 uri_index,
164 expanded: vec![root_id],
165 selected,
166 visible_rows: Vec::new(),
167 visible_dirty: true,
168 revision: 0,
169 };
170 store.rebuild_visible_rows_if_dirty();
171 store
172 }
173
174 /// Borrows the immutable root entry URI.
175 ///
176 /// # Examples
177 ///
178 /// ```
179 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
180 /// use ailloli_ui_widgets::files::FileTreeStore;
181 /// let root = FileEntry::new(FileUri::parse("file:///repo")?, FileMetadata::new(FileKind::Directory));
182 /// let store = FileTreeStore::new(root, None);
183 /// assert_eq!(store.root_uri().path(), "/repo");
184 /// # Ok::<(), ailloli_ui_fs::FileError>(())
185 /// ```
186 pub fn root_uri(&self) -> &FileUri {
187 &self.nodes[self.root.0].entry.uri
188 }
189
190 /// Returns the monotone, saturating presentation revision.
191 ///
192 /// Selection changes, expansion/cache invalidation, and child merges advance
193 /// it. A single high-level load can advance it more than once.
194 ///
195 /// # Examples
196 ///
197 /// ```
198 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
199 /// use ailloli_ui_widgets::files::FileTreeStore;
200 /// let root = FileEntry::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory));
201 /// let mut store = FileTreeStore::new(root, None);
202 /// store.set_selected(Some(FileUri::parse("file:///a")?));
203 /// assert_eq!(store.revision(), 1);
204 /// # Ok::<(), ailloli_ui_fs::FileError>(())
205 /// ```
206 pub fn revision(&self) -> u64 {
207 self.revision
208 }
209
210 /// Borrows the append-only arena, including detached historical records.
211 ///
212 /// Follow the root's `children` graph or use [`Self::to_file_explorer_nodes`]
213 /// when only the current attached tree is desired.
214 ///
215 /// # Examples
216 ///
217 /// ```
218 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
219 /// use ailloli_ui_widgets::files::FileTreeStore;
220 /// let root = FileEntry::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory));
221 /// let store = FileTreeStore::new(root, None);
222 /// assert_eq!(store.nodes().len(), 1);
223 /// # Ok::<(), ailloli_ui_fs::FileError>(())
224 /// ```
225 pub fn nodes(&self) -> &[FileTreeNode] {
226 &self.nodes
227 }
228
229 /// Rebuilds the root-first visible row cache when dirty, then borrows it.
230 ///
231 /// The root is always present. Descendants appear only below expanded
232 /// ancestors. Calling this method clears [`Self::visible_dirty`].
233 ///
234 /// # Examples
235 ///
236 /// ```
237 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
238 /// use ailloli_ui_widgets::files::{FileTreeNodeId, FileTreeStore};
239 /// let root = FileEntry::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory));
240 /// let mut store = FileTreeStore::new(root, None);
241 /// assert_eq!(store.visible_rows(), &[FileTreeNodeId(0)]);
242 /// # Ok::<(), ailloli_ui_fs::FileError>(())
243 /// ```
244 pub fn visible_rows(&mut self) -> &[FileTreeNodeId] {
245 self.rebuild_visible_rows_if_dirty();
246 &self.visible_rows
247 }
248
249 /// Reports whether the visible row cache needs rebuilding.
250 ///
251 /// # Examples
252 ///
253 /// ```
254 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
255 /// use ailloli_ui_widgets::files::FileTreeStore;
256 /// let root = FileEntry::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory));
257 /// let store = FileTreeStore::new(root, None);
258 /// assert!(!store.visible_dirty());
259 /// # Ok::<(), ailloli_ui_fs::FileError>(())
260 /// ```
261 pub fn visible_dirty(&self) -> bool {
262 self.visible_dirty
263 }
264
265 /// Clones currently expanded, still-addressable URIs in expansion order.
266 ///
267 /// Detached/out-of-bounds IDs are skipped. The root is included initially
268 /// but may be removed through [`Self::toggle_uri`] or [`Self::set_expanded_uris`].
269 ///
270 /// # Examples
271 ///
272 /// ```
273 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
274 /// use ailloli_ui_widgets::files::FileTreeStore;
275 /// let uri = FileUri::parse("file:///repo")?;
276 /// let store = FileTreeStore::new(FileEntry::new(uri.clone(), FileMetadata::new(FileKind::Directory)), None);
277 /// assert_eq!(store.expanded_uris(), vec![uri]);
278 /// # Ok::<(), ailloli_ui_fs::FileError>(())
279 /// ```
280 pub fn expanded_uris(&self) -> Vec<FileUri> {
281 self.expanded
282 .iter()
283 .filter_map(|id| self.nodes.get(id.0))
284 .map(|node| node.entry.uri.clone())
285 .collect()
286 }
287
288 /// Replaces the selected URI and advances revision only when changed.
289 ///
290 /// The URI is not validated against the root or index. Selection changes do
291 /// not invalidate visible rows; they affect filtering on the next merge.
292 ///
293 /// # Examples
294 ///
295 /// ```
296 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
297 /// use ailloli_ui_widgets::files::FileTreeStore;
298 /// let root = FileEntry::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory));
299 /// let mut store = FileTreeStore::new(root, None);
300 /// store.set_selected(Some(FileUri::parse("file:///a")?));
301 /// store.set_selected(Some(FileUri::parse("file:///a")?));
302 /// assert_eq!(store.revision(), 1);
303 /// # Ok::<(), ailloli_ui_fs::FileError>(())
304 /// ```
305 pub fn set_selected(&mut self, selected: Option<FileUri>) {
306 if self.selected != selected {
307 self.selected = selected;
308 self.revision = self.revision.saturating_add(1);
309 }
310 }
311
312 /// Replaces expansion state from known URIs, preserving order and uniqueness.
313 ///
314 /// Unknown URIs are ignored. A changed set invalidates visible rows and
315 /// advances revision; equal resolved IDs are a no-op.
316 ///
317 /// # Examples
318 ///
319 /// ```
320 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
321 /// use ailloli_ui_widgets::files::FileTreeStore;
322 /// let uri = FileUri::parse("file:///repo")?;
323 /// let mut store = FileTreeStore::new(FileEntry::new(uri.clone(), FileMetadata::new(FileKind::Directory)), None);
324 /// store.set_expanded_uris(&[]);
325 /// assert!(store.expanded_uris().is_empty() && store.visible_dirty());
326 /// # Ok::<(), ailloli_ui_fs::FileError>(())
327 /// ```
328 pub fn set_expanded_uris(&mut self, expanded: &[FileUri]) {
329 let mut next = Vec::new();
330 for uri in expanded {
331 if let Some(id) = self.node_id(uri) {
332 push_unique_id(&mut next, id);
333 }
334 }
335 if next != self.expanded {
336 self.expanded = next;
337 self.mark_visible_dirty();
338 }
339 }
340
341 /// Adds a known URI to expansion state without loading it.
342 ///
343 /// Unknown/already-expanded URIs are no-ops. A new expansion invalidates
344 /// visible rows and advances revision.
345 ///
346 /// # Examples
347 ///
348 /// ```
349 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
350 /// use ailloli_ui_widgets::files::FileTreeStore;
351 /// let uri = FileUri::parse("file:///repo")?;
352 /// let mut store = FileTreeStore::new(FileEntry::new(uri.clone(), FileMetadata::new(FileKind::Directory)), None);
353 /// store.set_expanded_uris(&[]);
354 /// store.expand_uri(&uri);
355 /// assert_eq!(store.expanded_uris(), vec![uri]);
356 /// # Ok::<(), ailloli_ui_fs::FileError>(())
357 /// ```
358 pub fn expand_uri(&mut self, uri: &FileUri) {
359 if let Some(id) = self.node_id(uri) {
360 self.expand_id(id);
361 }
362 }
363
364 /// Opens or closes a known URI without performing provider I/O.
365 ///
366 /// `open=true` deduplicates through [`Self::expand_uri`] semantics;
367 /// `false` removes every matching ID. Unknown/no-change requests are no-ops.
368 ///
369 /// # Examples
370 ///
371 /// ```
372 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
373 /// use ailloli_ui_widgets::files::FileTreeStore;
374 /// let uri = FileUri::parse("file:///repo")?;
375 /// let mut store = FileTreeStore::new(FileEntry::new(uri.clone(), FileMetadata::new(FileKind::Directory)), None);
376 /// store.toggle_uri(&uri, false);
377 /// assert!(store.expanded_uris().is_empty());
378 /// # Ok::<(), ailloli_ui_fs::FileError>(())
379 /// ```
380 pub fn toggle_uri(&mut self, uri: &FileUri, open: bool) {
381 let Some(id) = self.node_id(uri) else {
382 return;
383 };
384 if open {
385 self.expand_id(id);
386 } else {
387 let before = self.expanded.len();
388 self.expanded.retain(|item| item != &id);
389 if before != self.expanded.len() {
390 self.mark_visible_dirty();
391 }
392 }
393 }
394
395 /// Looks up the currently attached/indexed node for an exact URI.
396 ///
397 /// Detached historical arena nodes are deliberately absent.
398 ///
399 /// # Examples
400 ///
401 /// ```
402 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
403 /// use ailloli_ui_widgets::files::{FileTreeNodeId, FileTreeStore};
404 /// let uri = FileUri::parse("file:///repo")?;
405 /// let store = FileTreeStore::new(FileEntry::new(uri.clone(), FileMetadata::new(FileKind::Directory)), None);
406 /// assert_eq!(store.node_id(&uri), Some(FileTreeNodeId(0)));
407 /// # Ok::<(), ailloli_ui_fs::FileError>(())
408 /// ```
409 pub fn node_id(&self, uri: &FileUri) -> Option<FileTreeNodeId> {
410 self.uri_index.get(uri).copied()
411 }
412
413 /// Synchronously loads the root unless its state is already clean/active.
414 ///
415 /// Provider errors are retained as [`DirLoadState::Error`] rather than
416 /// returned. A loaded root is cached and not reread by this method.
417 ///
418 /// # Examples
419 ///
420 /// ```
421 /// use ailloli_ui_fs::FileProvider;
422 /// use ailloli_ui_widgets::files::{FileTreeOptions, FileTreeStore};
423 /// fn load(store: &mut FileTreeStore, provider: &dyn FileProvider) {
424 /// store.load_root(provider, FileTreeOptions::default());
425 /// }
426 /// # let _ = load;
427 /// ```
428 pub fn load_root(&mut self, provider: &dyn FileProvider, options: FileTreeOptions) {
429 self.load_directory(self.root, provider, options, false);
430 }
431
432 /// Loads and expands each currently discoverable root-to-target ancestor.
433 ///
434 /// Traversal stops silently when the target is outside the root or a next
435 /// ancestor is absent after the preceding load. Provider errors are retained
436 /// in node state; they are not returned.
437 ///
438 /// # Examples
439 ///
440 /// ```
441 /// use ailloli_ui_fs::{FileProvider, FileUri};
442 /// use ailloli_ui_widgets::files::{FileTreeOptions, FileTreeStore};
443 /// fn reveal(store: &mut FileTreeStore, provider: &dyn FileProvider, target: &FileUri) {
444 /// store.ensure_loaded_path(provider, target, FileTreeOptions::default());
445 /// }
446 /// # let _ = reveal;
447 /// ```
448 pub fn ensure_loaded_path(
449 &mut self,
450 provider: &dyn FileProvider,
451 target: &FileUri,
452 options: FileTreeOptions,
453 ) {
454 let root = self.root_uri().clone();
455 for uri in file_uri_ancestors_between(&root, target) {
456 let Some(id) = self.node_id(&uri) else {
457 return;
458 };
459 self.load_directory(id, provider, options, false);
460 self.expand_id(id);
461 }
462 }
463
464 /// Synchronously preloads ordinary directories for `depth` edges from root.
465 ///
466 /// The root itself is always considered, even at depth zero. Symlink policy
467 /// treats descendant reads as proactive [`FileTreeLoadMode`](super::FileTreeLoadMode)
468 /// work. The `options.max_depth` field is not consulted directly here;
469 /// callers choose the explicit `depth` bound.
470 ///
471 /// # Examples
472 ///
473 /// ```
474 /// use ailloli_ui_fs::FileProvider;
475 /// use ailloli_ui_widgets::files::{FileTreeOptions, FileTreeStore};
476 /// fn preload(store: &mut FileTreeStore, provider: &dyn FileProvider) {
477 /// store.preload_depth(provider, 2, FileTreeOptions::default());
478 /// }
479 /// # let _ = preload;
480 /// ```
481 pub fn preload_depth(
482 &mut self,
483 provider: &dyn FileProvider,
484 depth: usize,
485 options: FileTreeOptions,
486 ) {
487 self.preload_depth_from(self.root, provider, depth, options);
488 }
489
490 /// Preloads from root through `options.max_depth` edges.
491 ///
492 /// This is a convenience over [`Self::preload_depth`]; it does not require
493 /// `options.load_mode` to be [`FileTreeLoadMode::Full`](super::FileTreeLoadMode::Full).
494 ///
495 /// # Examples
496 ///
497 /// ```
498 /// use ailloli_ui_fs::FileProvider;
499 /// use ailloli_ui_widgets::files::{FileTreeOptions, FileTreeStore};
500 /// fn load_all(store: &mut FileTreeStore, provider: &dyn FileProvider) {
501 /// store.full_load(provider, FileTreeOptions { max_depth: 3, ..FileTreeOptions::default() });
502 /// }
503 /// # let _ = load_all;
504 /// ```
505 pub fn full_load(&mut self, provider: &dyn FileProvider, options: FileTreeOptions) {
506 self.preload_depth_from(self.root, provider, options.max_depth, options);
507 }
508
509 /// Synchronously lists one directory and replaces its retained children.
510 ///
511 /// `force_reload` rereads only a clean `Loaded` node; it does not override
512 /// `NotDirectory` or `Loading`. Unloaded, dirty, and error states retry.
513 /// Canonical symlink cycles and provider errors clear children, retain an
514 /// error message, dirty visible rows, and return normally.
515 ///
516 /// # Panics
517 ///
518 /// Panics when `id` is outside this store's arena.
519 ///
520 /// # Examples
521 ///
522 /// ```
523 /// use ailloli_ui_fs::FileProvider;
524 /// use ailloli_ui_widgets::files::{FileTreeNodeId, FileTreeOptions, FileTreeStore};
525 /// fn reload_root(store: &mut FileTreeStore, provider: &dyn FileProvider) {
526 /// store.load_directory(FileTreeNodeId(0), provider, FileTreeOptions::default(), true);
527 /// }
528 /// # let _ = reload_root;
529 /// ```
530 pub fn load_directory(
531 &mut self,
532 id: FileTreeNodeId,
533 provider: &dyn FileProvider,
534 options: FileTreeOptions,
535 force_reload: bool,
536 ) {
537 if !self.should_load(id, force_reload) {
538 return;
539 }
540 if !node_is_loadable(
541 &self.nodes[id.0].entry.metadata,
542 options,
543 ChildLoadReason::Explicit,
544 ) {
545 self.nodes[id.0].load_state = DirLoadState::NotDirectory;
546 self.mark_visible_dirty();
547 return;
548 }
549 match self.node_has_canonical_cycle(id, provider) {
550 Ok(true) => {
551 self.nodes[id.0].children.clear();
552 self.nodes[id.0].load_state = DirLoadState::Error {
553 message: "symlink cycle".into(),
554 };
555 self.mark_visible_dirty();
556 return;
557 }
558 Ok(false) => {}
559 Err(err) => {
560 self.nodes[id.0].children.clear();
561 self.nodes[id.0].load_state = DirLoadState::Error {
562 message: err.to_string(),
563 };
564 self.mark_visible_dirty();
565 return;
566 }
567 }
568 self.nodes[id.0].load_state = DirLoadState::Loading;
569 self.mark_visible_dirty();
570 match provider.read_dir(&self.nodes[id.0].entry.uri) {
571 Ok(entries) => self.merge_children(id, entries, options),
572 Err(err) => {
573 self.nodes[id.0].children.clear();
574 self.nodes[id.0].load_state = DirLoadState::Error {
575 message: err.to_string(),
576 };
577 self.mark_visible_dirty();
578 }
579 }
580 }
581
582 /// Filters, sorts, truncates, and replaces one node's child listing.
583 ///
584 /// Existing child URI indexes and expansion entries are detached recursively;
585 /// arena records remain. New IDs append in sorted order. A truncated listing
586 /// sets [`DirLoadState::Dirty`]; otherwise `Loaded.entry_count` excludes any
587 /// synthetic UI placeholder. Revision advances with saturation and visible
588 /// rows become dirty.
589 ///
590 /// # Panics
591 ///
592 /// Panics when `parent` is outside this store's arena.
593 ///
594 /// # Examples
595 ///
596 /// ```
597 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
598 /// use ailloli_ui_widgets::files::{FileTreeNodeId, FileTreeOptions, FileTreeStore};
599 /// let root_uri = FileUri::parse("file:///repo")?;
600 /// let mut store = FileTreeStore::new(FileEntry::new(root_uri, FileMetadata::new(FileKind::Directory)), None);
601 /// let child = FileEntry::new(FileUri::parse("file:///repo/main.rs")?, FileMetadata::new(FileKind::File));
602 /// store.merge_children(FileTreeNodeId(0), vec![child], FileTreeOptions::default());
603 /// assert_eq!(store.to_file_explorer_nodes()[0].children[0].name(), "main.rs");
604 /// # Ok::<(), ailloli_ui_fs::FileError>(())
605 /// ```
606 pub fn merge_children(
607 &mut self,
608 parent: FileTreeNodeId,
609 entries: Vec<FileEntry>,
610 options: FileTreeOptions,
611 ) {
612 let selected = self.selected.as_ref();
613 let mut entries = entries
614 .into_iter()
615 .filter(|entry| should_include_file_entry(entry, selected, options))
616 .collect::<Vec<_>>();
617 sort_file_entries(&mut entries);
618 let truncated = truncate_entries(&mut entries, options);
619
620 let old_children = self.nodes[parent.0].children.clone();
621 for child in old_children {
622 self.remove_subtree_index(child);
623 }
624
625 let depth = self.nodes[parent.0].depth + 1;
626 let mut child_ids = Vec::with_capacity(entries.len());
627 for entry in entries {
628 let id = FileTreeNodeId(self.nodes.len());
629 self.uri_index.insert(entry.uri.clone(), id);
630 child_ids.push(id);
631 self.nodes.push(FileTreeNode {
632 id,
633 parent: Some(parent),
634 canonical_uri: None,
635 load_state: dir_load_state_for_metadata(&entry.metadata, options),
636 entry,
637 children: Vec::new(),
638 depth,
639 });
640 }
641
642 self.nodes[parent.0].children = child_ids;
643 self.nodes[parent.0].load_state = DirLoadState::Loaded {
644 revision: self.revision.saturating_add(1),
645 entry_count: self.nodes[parent.0].children.len(),
646 };
647 if truncated {
648 self.nodes[parent.0].load_state = DirLoadState::Dirty;
649 }
650 self.revision = self.revision.saturating_add(1);
651 self.mark_visible_dirty();
652 }
653
654 /// Clones the currently attached arena graph into one recursive root node.
655 ///
656 /// Loading/error nodes are disabled. Expanded loading/error/dirty nodes gain
657 /// one synthetic disabled placeholder; collapsed nodes keep real children in
658 /// the snapshot but omit the placeholder.
659 ///
660 /// # Examples
661 ///
662 /// ```
663 /// use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileUri};
664 /// use ailloli_ui_widgets::files::FileTreeStore;
665 /// let root = FileEntry::new(FileUri::parse("file:///repo")?, FileMetadata::new(FileKind::Directory));
666 /// let store = FileTreeStore::new(root, None);
667 /// let nodes = store.to_file_explorer_nodes();
668 /// assert_eq!((nodes.len(), nodes[0].name()), (1, "repo"));
669 /// # Ok::<(), ailloli_ui_fs::FileError>(())
670 /// ```
671 pub fn to_file_explorer_nodes(&self) -> Vec<FileExplorerNode> {
672 vec![self.node_to_file_explorer_node(self.root)]
673 }
674
675 /// Recursively clones an attached arena subtree and decorates current state.
676 fn node_to_file_explorer_node(&self, id: FileTreeNodeId) -> FileExplorerNode {
677 let node = &self.nodes[id.0];
678 let mut out = FileExplorerNode::new(node.entry.clone());
679 out.disabled = matches!(
680 node.load_state,
681 DirLoadState::Loading | DirLoadState::Error { .. }
682 );
683 out.children = node
684 .children
685 .iter()
686 .map(|child| self.node_to_file_explorer_node(*child))
687 .collect();
688 if self.is_expanded(id) {
689 match &node.load_state {
690 DirLoadState::Loading => out.children.push(loading_placeholder(&node.entry.uri)),
691 DirLoadState::Error { message } => {
692 out.children
693 .push(error_placeholder(&node.entry.uri, message.as_str()));
694 }
695 DirLoadState::Dirty => out
696 .children
697 .push(large_directory_placeholder(&node.entry.uri)),
698 DirLoadState::NotDirectory
699 | DirLoadState::Unloaded
700 | DirLoadState::Loaded { .. } => {}
701 }
702 }
703 out
704 }
705
706 /// Applies load-state cache/retry rules; assumes a valid arena ID.
707 fn should_load(&self, id: FileTreeNodeId, force_reload: bool) -> bool {
708 match self.nodes[id.0].load_state {
709 DirLoadState::NotDirectory | DirLoadState::Loading => false,
710 DirLoadState::Unloaded | DirLoadState::Dirty | DirLoadState::Error { .. } => true,
711 DirLoadState::Loaded { .. } => force_reload,
712 }
713 }
714
715 /// Depth-bounded synchronous DFS that applies proactive symlink policy.
716 fn preload_depth_from(
717 &mut self,
718 id: FileTreeNodeId,
719 provider: &dyn FileProvider,
720 remaining_depth: usize,
721 options: FileTreeOptions,
722 ) {
723 self.load_directory(id, provider, options, false);
724 if remaining_depth == 0 {
725 return;
726 }
727 let children = self.nodes[id.0].children.clone();
728 for child in children {
729 if node_is_loadable(
730 &self.nodes[child.0].entry.metadata,
731 options,
732 ChildLoadReason::Preload,
733 ) {
734 self.preload_depth_from(child, provider, remaining_depth - 1, options);
735 }
736 }
737 }
738
739 /// Deduplicates one expansion ID and invalidates visible rows on insertion.
740 fn expand_id(&mut self, id: FileTreeNodeId) {
741 if !self.expanded.iter().any(|item| item == &id) {
742 self.expanded.push(id);
743 self.mark_visible_dirty();
744 }
745 }
746
747 /// Tests expansion membership by store-local ID.
748 fn is_expanded(&self, id: FileTreeNodeId) -> bool {
749 self.expanded.iter().any(|item| item == &id)
750 }
751
752 /// Replaces the root-first DFS cache only after an invalidating mutation.
753 fn rebuild_visible_rows_if_dirty(&mut self) {
754 if !self.visible_dirty {
755 return;
756 }
757 let mut rows = Vec::new();
758 self.push_visible_subtree(self.root, &mut rows);
759 self.visible_rows = rows;
760 self.visible_dirty = false;
761 }
762
763 /// Appends a node and recursively appends children only while expanded.
764 fn push_visible_subtree(&self, id: FileTreeNodeId, out: &mut Vec<FileTreeNodeId>) {
765 out.push(id);
766 if !self.is_expanded(id) {
767 return;
768 }
769 for child in &self.nodes[id.0].children {
770 self.push_visible_subtree(*child, out);
771 }
772 }
773
774 /// Marks the row cache dirty and advances the saturating revision.
775 fn mark_visible_dirty(&mut self) {
776 self.visible_dirty = true;
777 self.revision = self.revision.saturating_add(1);
778 }
779
780 /// Detaches URI indexes/expansion recursively without reclaiming arena slots.
781 fn remove_subtree_index(&mut self, id: FileTreeNodeId) {
782 let node = &self.nodes[id.0];
783 self.uri_index.remove(&node.entry.uri);
784 let children = node.children.clone();
785 for child in children {
786 self.remove_subtree_index(child);
787 }
788 self.expanded.retain(|expanded| expanded != &id);
789 }
790
791 /// Detects equality between this node's canonical URI and any ancestor's.
792 ///
793 /// # Errors
794 ///
795 /// Propagates the first [`ailloli_ui_fs::FileError`] returned while querying
796 /// or memoizing the selected node's or an ancestor's canonical URI.
797 ///
798 /// # Panics
799 ///
800 /// Panics if `id` or a recorded parent does not index the private node arena.
801 fn node_has_canonical_cycle(
802 &mut self,
803 id: FileTreeNodeId,
804 provider: &dyn FileProvider,
805 ) -> Result<bool, ailloli_ui_fs::FileError> {
806 let Some(canonical) = self.ensure_canonical_uri(id, provider)? else {
807 return Ok(false);
808 };
809 let mut parent = self.nodes[id.0].parent;
810 while let Some(parent_id) = parent {
811 if self.ensure_canonical_uri(parent_id, provider)? == Some(canonical.clone()) {
812 return Ok(true);
813 }
814 parent = self.nodes[parent_id.0].parent;
815 }
816 Ok(false)
817 }
818
819 /// Queries and memoizes one provider canonical URI when present.
820 ///
821 /// Because `None` is also the uninitialized sentinel, providers that return
822 /// `None` are queried again on later checks.
823 ///
824 /// # Errors
825 ///
826 /// Propagates the provider's [`ailloli_ui_fs::FileError`] from
827 /// [`FileProvider::canonical_uri`]; the cache remains `None` on failure.
828 ///
829 /// # Panics
830 ///
831 /// Panics if `id` does not index the private node arena.
832 fn ensure_canonical_uri(
833 &mut self,
834 id: FileTreeNodeId,
835 provider: &dyn FileProvider,
836 ) -> Result<Option<FileUri>, ailloli_ui_fs::FileError> {
837 if self.nodes[id.0].canonical_uri.is_none() {
838 self.nodes[id.0].canonical_uri = provider.canonical_uri(&self.nodes[id.0].entry.uri)?;
839 }
840 Ok(self.nodes[id.0].canonical_uri.clone())
841 }
842}
843
844/// Initializes loadable directory-like metadata as unloaded, otherwise leaf-like.
845fn dir_load_state_for_metadata(metadata: &FileMetadata, options: FileTreeOptions) -> DirLoadState {
846 if node_is_loadable(metadata, options, ChildLoadReason::Explicit) {
847 DirLoadState::Unloaded
848 } else {
849 DirLoadState::NotDirectory
850 }
851}
852
853/// Combines directory-like metadata with explicit/preload symlink policy.
854fn node_is_loadable(
855 metadata: &FileMetadata,
856 options: FileTreeOptions,
857 reason: ChildLoadReason,
858) -> bool {
859 metadata.is_directory_like()
860 && symlink_policy_allows_descend(metadata, reason, options.symlink_traversal_policy)
861}
862
863/// Appends an ID only when it is not already present, preserving order.
864fn push_unique_id(out: &mut Vec<FileTreeNodeId>, id: FileTreeNodeId) {
865 if !out.iter().any(|item| item == &id) {
866 out.push(id);
867 }
868}
869
870#[cfg(test)]
871/// Scenario tests for caching, visibility, exclusions, symlinks, and cycles.
872mod tests {
873 use std::cell::Cell;
874 use std::collections::HashMap;
875
876 use super::super::tree::FileTreeLoadMode;
877 use ailloli_ui_fs::{FileCapabilities, FileError, FileKind, FileMetadata};
878
879 use super::*;
880
881 /// In-memory provider that counts directory reads and supports canonical maps.
882 #[derive(Default)]
883 struct CountingProvider {
884 metadata: HashMap<FileUri, FileMetadata>,
885 dirs: HashMap<FileUri, Vec<FileEntry>>,
886 canonical: HashMap<FileUri, FileUri>,
887 read_count: Cell<usize>,
888 }
889
890 impl CountingProvider {
891 /// Adds a directory and simple child metadata to the provider fixture.
892 fn dir(mut self, path: &str, entries: &[(&str, FileKind)]) -> Self {
893 let uri = uri(path);
894 self.metadata
895 .insert(uri.clone(), FileMetadata::new(FileKind::Directory));
896 let entries = entries
897 .iter()
898 .map(|(name, kind)| {
899 let child = child_uri(path, name);
900 self.metadata
901 .insert(child.clone(), FileMetadata::new(*kind));
902 FileEntry {
903 uri: child,
904 name: (*name).to_string(),
905 metadata: FileMetadata::new(*kind),
906 }
907 })
908 .collect::<Vec<_>>();
909 self.dirs.insert(uri, entries);
910 self
911 }
912
913 /// Adds a directory with fully specified child metadata.
914 fn dir_entries(mut self, path: &str, entries: Vec<FileEntry>) -> Self {
915 let uri = uri(path);
916 self.metadata
917 .insert(uri.clone(), FileMetadata::new(FileKind::Directory));
918 for entry in &entries {
919 self.metadata
920 .insert(entry.uri.clone(), entry.metadata.clone());
921 }
922 self.dirs.insert(uri, entries);
923 self
924 }
925
926 /// Registers a canonical URI response for cycle scenarios.
927 fn canonical(mut self, path: &str, canonical_path: &str) -> Self {
928 self.canonical.insert(uri(path), uri(canonical_path));
929 self
930 }
931
932 /// Returns the standard `/repo` directory root fixture.
933 fn root_entry(&self) -> FileEntry {
934 FileEntry::new(uri("/repo"), FileMetadata::new(FileKind::Directory))
935 }
936 }
937
938 impl FileProvider for CountingProvider {
939 fn capabilities(&self) -> FileCapabilities {
940 FileCapabilities::READ_ONLY
941 }
942
943 fn read_dir(&self, uri: &FileUri) -> Result<Vec<FileEntry>, FileError> {
944 self.read_count.set(self.read_count.get() + 1);
945 Ok(self.dirs.get(uri).cloned().unwrap_or_default())
946 }
947
948 fn read_file(&self, _uri: &FileUri) -> Result<Vec<u8>, FileError> {
949 Err(FileError::Unsupported("mock read_file".into()))
950 }
951
952 fn write_file(&self, _uri: &FileUri, _bytes: &[u8]) -> Result<(), FileError> {
953 Err(FileError::Unsupported("mock write_file".into()))
954 }
955
956 fn metadata(&self, uri: &FileUri) -> Result<FileMetadata, FileError> {
957 self.metadata
958 .get(uri)
959 .cloned()
960 .ok_or_else(|| FileError::NotFound(uri.to_string()))
961 }
962
963 fn canonical_uri(&self, uri: &FileUri) -> Result<Option<FileUri>, FileError> {
964 Ok(self.canonical.get(uri).cloned())
965 }
966
967 fn create_dir(&self, _uri: &FileUri) -> Result<(), FileError> {
968 Err(FileError::Unsupported("mock create_dir".into()))
969 }
970
971 fn rename(&self, _from: &FileUri, _to: &FileUri) -> Result<(), FileError> {
972 Err(FileError::Unsupported("mock rename".into()))
973 }
974
975 fn remove(&self, _uri: &FileUri) -> Result<(), FileError> {
976 Err(FileError::Unsupported("mock remove".into()))
977 }
978 }
979
980 #[test]
981 fn store_caches_loaded_directories_after_collapse_reopen() {
982 let provider = CountingProvider::default()
983 .dir("/repo", &[("src", FileKind::Directory)])
984 .dir("/repo/src", &[("lib.rs", FileKind::File)]);
985 let mut store = FileTreeStore::new(provider.root_entry(), None);
986 let options = FileTreeOptions::default();
987
988 store.load_root(&provider, options);
989 let src = uri("/repo/src");
990 let src_id = store.node_id(&src).expect("src id");
991 store.load_directory(src_id, &provider, options, false);
992 let reads_after_load = provider.read_count.get();
993
994 store.toggle_uri(&src, false);
995 store.toggle_uri(&src, true);
996 store.load_directory(src_id, &provider, options, false);
997
998 assert_eq!(provider.read_count.get(), reads_after_load);
999 assert!(store.to_file_explorer_nodes()[0]
1000 .children
1001 .iter()
1002 .any(|node| node.name() == "src"));
1003 }
1004
1005 #[test]
1006 fn store_visible_rows_rebuild_only_when_dirty() {
1007 let provider = CountingProvider::default()
1008 .dir("/repo", &[("src", FileKind::Directory)])
1009 .dir("/repo/src", &[("lib.rs", FileKind::File)]);
1010 let mut store = FileTreeStore::new(provider.root_entry(), None);
1011 store.load_root(&provider, FileTreeOptions::default());
1012
1013 assert!(store.visible_dirty());
1014 assert_eq!(store.visible_rows().len(), 2);
1015 assert!(!store.visible_dirty());
1016
1017 store.toggle_uri(&uri("/repo/src"), true);
1018 assert!(store.visible_dirty());
1019 assert_eq!(store.visible_rows().len(), 2);
1020 }
1021
1022 #[test]
1023 fn store_exclusions_and_large_placeholders_are_stable() {
1024 let provider = CountingProvider::default().dir(
1025 "/repo",
1026 &[
1027 ("target", FileKind::Directory),
1028 ("src", FileKind::Directory),
1029 ("z.rs", FileKind::File),
1030 ("a.rs", FileKind::File),
1031 ],
1032 );
1033 let mut store = FileTreeStore::new(provider.root_entry(), None);
1034 store.load_root(
1035 &provider,
1036 FileTreeOptions {
1037 exclude_defaults: true,
1038 max_entries_per_directory: Some(2),
1039 large_directory_policy: super::super::tree::LargeDirectoryPolicy::Placeholder,
1040 ..FileTreeOptions::default()
1041 },
1042 );
1043
1044 let nodes = store.to_file_explorer_nodes();
1045 let names = nodes[0]
1046 .children
1047 .iter()
1048 .map(FileExplorerNode::name)
1049 .collect::<Vec<_>>();
1050 assert!(!names.contains(&"target"));
1051 assert!(names.contains(&"src"));
1052 assert!(names.iter().any(|name| name.contains("Large directory")));
1053 }
1054
1055 #[test]
1056 fn store_explicitly_loads_symlink_directory() {
1057 let provider = CountingProvider::default()
1058 .dir_entries(
1059 "/repo",
1060 vec![entry_with_metadata(
1061 "/repo/linked",
1062 "linked",
1063 symlink_metadata(Some(FileKind::Directory)),
1064 )],
1065 )
1066 .dir("/repo/linked", &[("child.rs", FileKind::File)]);
1067 let mut store = FileTreeStore::new(provider.root_entry(), None);
1068 let options = FileTreeOptions::default();
1069
1070 store.load_root(&provider, options);
1071 let linked = uri("/repo/linked");
1072 let linked_id = store.node_id(&linked).expect("linked id");
1073 store.load_directory(linked_id, &provider, options, false);
1074
1075 let nodes = store.to_file_explorer_nodes();
1076 let linked = child(&nodes[0], "linked");
1077 assert!(linked.children.iter().any(|node| node.name() == "child.rs"));
1078 }
1079
1080 #[test]
1081 fn store_full_load_does_not_preload_symlink_directories_by_default() {
1082 let provider = CountingProvider::default()
1083 .dir_entries(
1084 "/repo",
1085 vec![entry_with_metadata(
1086 "/repo/linked",
1087 "linked",
1088 symlink_metadata(Some(FileKind::Directory)),
1089 )],
1090 )
1091 .dir("/repo/linked", &[("child.rs", FileKind::File)]);
1092 let mut store = FileTreeStore::new(provider.root_entry(), None);
1093
1094 store.full_load(
1095 &provider,
1096 FileTreeOptions {
1097 load_mode: FileTreeLoadMode::Full,
1098 ..FileTreeOptions::default()
1099 },
1100 );
1101
1102 let nodes = store.to_file_explorer_nodes();
1103 assert!(child(&nodes[0], "linked").children.is_empty());
1104 }
1105
1106 #[test]
1107 fn store_symlink_cycle_does_not_recurse_forever() {
1108 let provider = CountingProvider::default()
1109 .dir_entries(
1110 "/repo",
1111 vec![entry_with_metadata(
1112 "/repo/loop",
1113 "loop",
1114 symlink_metadata(Some(FileKind::Directory)),
1115 )],
1116 )
1117 .dir("/repo/loop", &[("unreachable.rs", FileKind::File)])
1118 .canonical("/repo", "/repo")
1119 .canonical("/repo/loop", "/repo");
1120 let mut store = FileTreeStore::new(provider.root_entry(), None);
1121 let options = FileTreeOptions::default();
1122
1123 store.load_root(&provider, options);
1124 let loop_uri = uri("/repo/loop");
1125 store.toggle_uri(&loop_uri, true);
1126 let loop_id = store.node_id(&loop_uri).expect("loop id");
1127 store.load_directory(loop_id, &provider, options, false);
1128
1129 let nodes = store.to_file_explorer_nodes();
1130 let loop_node = child(&nodes[0], "loop");
1131 assert!(loop_node
1132 .children
1133 .iter()
1134 .any(|node| node.name().contains("symlink cycle")));
1135 assert!(!loop_node
1136 .children
1137 .iter()
1138 .any(|node| node.name() == "unreachable.rs"));
1139 }
1140
1141 /// Joins a child name onto a fixture path.
1142 fn child_uri(parent: &str, name: &str) -> FileUri {
1143 uri(&format!("{}/{}", parent.trim_end_matches('/'), name))
1144 }
1145
1146 /// Finds a named child or panics with parent context.
1147 fn child<'a>(node: &'a FileExplorerNode, name: &str) -> &'a FileExplorerNode {
1148 node.children
1149 .iter()
1150 .find(|child| child.name() == name)
1151 .unwrap_or_else(|| panic!("missing child {name} in {}", node.name()))
1152 }
1153
1154 /// Builds an entry fixture with caller-provided metadata.
1155 fn entry_with_metadata(
1156 path: &str,
1157 name: impl Into<String>,
1158 metadata: FileMetadata,
1159 ) -> FileEntry {
1160 FileEntry {
1161 uri: uri(path),
1162 name: name.into(),
1163 metadata,
1164 }
1165 }
1166
1167 /// Builds symlink metadata with an optional resolved target kind.
1168 fn symlink_metadata(target: Option<FileKind>) -> FileMetadata {
1169 let mut metadata = FileMetadata::new(FileKind::Symlink);
1170 metadata.symlink_target_kind = target;
1171 metadata
1172 }
1173
1174 /// Parses an absolute fixture path in the local file namespace.
1175 fn uri(path: &str) -> FileUri {
1176 FileUri::parse(format!("file://{path}")).expect("file uri")
1177 }
1178}