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}