Struct Index 

pub struct Index { /* private fields */ }

The in-memory hierarchical index.

Implementations

impl Index

pub fn new(root_path: impl Into<PathBuf>) -> Self

Create an empty index rooted at root_path, under ScanScope::default.

That is the scope of ScanConfig::default, which observes control state, so this index answers Self::is_ignored, Self::controls, and the partition accessors (Self::partition_total, Self::partition_rollup, and Self::partition_rollup_summary), and it accepts control input. Build any other scope, including one that turns control observation off, with Self::new_with_scope.

pub fn new_with_scope(root_path: impl Into<PathBuf>, scope: ScanScope) -> Self

Create an empty index with an explicit semantic scan scope.

Its control table applies the default ControlLimits, whatever limits the scope was taken under, so a snapshot of it saves only when those agree. Build an index for any other limits with Self::new_with_config.

pub fn new_with_config( root_path: impl Into<PathBuf>, config: &ScanConfig, ) -> Self

Create an empty index with the scope, file-type rules, and control limits of config, as the scans behind crate::open and crate::OpenedIndex do.

The scope and the control table come from one configuration, so the table enforces exactly the limits the scope’s ignore-rules identity claims.

pub fn types(&self) -> &TypeRegistry

The file-type rules this index classifies against.

pub fn controls(&self) -> Result<&ControlTable>

Exact fixed control state retained by this detached index.

Errors

crate::Error::ControlStateNotObserved when the index was built without observing control state (ScanScope::observes_controls). Its table is empty because nothing was read, and returning it would claim the tree has no control files.

pub const fn observes_controls(&self) -> bool

Whether this index observed .gitignore control state, and so can answer Self::is_ignored and Self::controls.

pub fn control_identity(&self) -> ControlTierIdentity

Whether this index observed .gitignore control state, and under which limits.

pub fn snapshot_identity(&self) -> SnapshotIdentity

The identity of every tier a snapshot of this index holds.

pub fn control_coverage(&self) -> ControlCoverage

Whether this index’s ignore classification applies every control file in scope.

crate::control::ControlCoverage::NotObserved when the index read no control file. Otherwise the limits, the applied and refused counts, and the first refused files. Sizes and counts are exact either way; only the ignored and unignored split below a refused file is not.

pub fn classify(&self, relative_path: &Path) -> Classification

Classify one relative path under this index’s rules, without opening the file.

pub fn root_path(&self) -> &Path

The absolute path this index is rooted at.

pub const fn scope(&self) -> ScanScope

Semantic scope represented by this index and any snapshot written from it.

pub fn freshness(&self) -> Freshness

Trust state for the whole index.

pub fn freshness_at(&self, path: &Path) -> Freshness

Trust state for one subtree, including any stale descendant it contains.

pub fn clock(&self) -> Clock

The clock of the most recently applied commit.

pub fn len(&self) -> u64

Number of live entries, including the root.

pub fn is_empty(&self) -> bool

True when the index holds nothing but its root.

pub fn total(&self) -> RollUp

Owned, self-describing roll-up state for the whole tree.

pub fn partition_total(&self) -> Result<PartitionRollUp>

Both fixed aggregate partitions for the complete tree.

Errors

crate::Error::ControlStateNotObserved when the index did not observe control state: its unignored partition equals all only because no rule was read. Self::total answers the all partition for any index.

pub fn apply(&mut self, observation: &Observation) -> Result<ApplyOutcome>

Arbitrate a producer observation and commit its effective mutations.

Conditional operations are accepted only while their baseline still matches. No-ops and stale operations do not advance the clock or enter the journal.

A control operation on an index that does not observe control state (Self::observes_controls) fails the whole batch with crate::Error::ControlStateNotObserved, whatever its baseline.

pub fn path_state(&self, path: &Path) -> PathState

Current user-visible state for one path.

Conditional producers should capture Self::expectation so ABA and structural races cannot return to the same visible state unnoticed.

pub fn expectation(&self, path: &Path) -> PathExpectation

Conditional baseline with target and nearest-ancestor ABA protection.

pub fn since(&self, clock: Clock) -> Since

Exact commits applied since clock, oldest first.

pub fn take_pending_invalidations(&mut self) -> Vec<(PathBuf, InvalidateReason)>

Take the subtrees that producers escalated for re-scan.

The caller is expected to hand these to the scan layer, which turns them back into precise commits. Escalation is closed-loop: draining this list without re-scanning is what makes an index silently diverge.

pub fn lookup(&self, path: &Path) -> Option<EntryId>

Look up an entry id by path relative to the root.

pub fn rollup(&self, path: &Path) -> Option<RollUp>

Owned, self-describing roll-up state for a directory by relative path. The empty path is the root.

pub fn partition_rollup(&self, path: &Path) -> Result<Option<PartitionRollUp>>

Both fixed aggregate partitions for a directory by relative path.

Ok(None) when the path is absent or not a directory.

Errors

crate::Error::ControlStateNotObserved when the index did not observe control state, whatever the path, as Self::partition_total refuses.

pub fn partition_rollup_summary( &self, path: &Path, ) -> Result<Option<PartitionRollUpSummary>>

Both constant-size aggregate partitions for a directory.

Ok(None) when the path is absent or not a directory.

Errors

crate::Error::ControlStateNotObserved when the index did not observe control state, whatever the path, as Self::partition_total refuses.

pub fn attrs(&self, path: &Path) -> Option<&Attrs>

Attributes for any entry, by relative path.

pub fn kind(&self, path: &Path) -> Option<EntryKind>

Kind of an entry, by relative path.

pub fn is_ignored(&self, path: &Path) -> Result<Option<bool>>

Effective fixed-control classification for one retained entry.

Ok(Some(ignored)) when a retained entry’s governing controls are known; Ok(None) for a missing entry or one below a refused control source.

Errors

crate::Error::ControlStateNotObserved when the index was built without observing control state, whatever the path. Every entry of such an index carries “not ignored” only because no rule was read, so that answer would be silently wrong for a tree that has a .gitignore.

pub fn ignored_classification(&self, path: &Path) -> Option<bool>

Known ignore classification of a retained path, or None when unavailable.

A refusal may hide an ignore or a negation. Its descendants cannot be counted as known members of either population.

pub fn ignored_classification_complete_below(&self, path: &Path) -> bool

Whether ignored classification is known throughout this retained subtree.

pub fn children( &self, path: &Path, ) -> Option<impl DoubleEndedIterator<Item = (&OsStr, EntryId)> + ExactSizeIterator + '_>

Borrow direct children of a directory as (name, id) pairs in name order.

The iterator borrows this owned index and allocates nothing.

pub fn children_of( &self, id: EntryId, ) -> Option<impl DoubleEndedIterator<Item = (&OsStr, EntryId)> + ExactSizeIterator + '_>

Borrow direct children of an entry id as (name, id) pairs in name order.

Returns None for a stale handle. A live non-directory returns an empty iterator.

pub fn path_of(&self, id: EntryId) -> Option<PathBuf>

Reconstruct an entry’s path relative to the root by walking parent pointers.

pub fn rollup_of(&self, id: EntryId) -> Option<RollUp>

Owned, self-describing roll-up state for an entry id, if it is a directory.

pub fn attrs_of(&self, id: EntryId) -> Option<&Attrs>

Attributes for an entry id, or None when the handle is stale.

pub fn kind_of(&self, id: EntryId) -> Option<EntryKind>

Kind for an entry id, or None when the handle is stale.

pub fn name_of(&self, id: EntryId) -> Option<&OsStr>

Name for an entry id. The root’s name is empty; stale handles return None.

pub fn content(&self) -> Option<&ContentIndex>

Sparse content tier, when analysis has been enabled.

pub fn content_rollup(&self, path: &Path) -> Option<&ContentRollUp>

Precomputed content rollup for one relative directory.

pub fn content_set(&self) -> AnalysisSet

The analyzer set this index’s content tier holds records for, or AnalysisSet::NONE when it holds no content tier.

pub fn content_identity(&self, analysis: AnalysisSet) -> ContentTierIdentity

The content tier identity this index gives records of analysis: its own entry tier, which holds its type rules, the analyzer set, and the analyzers’ versions and options.

pub fn clear_content(&mut self)

Drop all derived content while preserving metadata and snapshot compatibility.

pub fn provenance(&self, path: &Path) -> Option<Provenance>

Provenance of one path: where its value came from, when, and how settled.

Built on demand from the entry’s stored source and the index’s timestamps rather than read from a field, because the timestamps are shared by nearly every entry and storing them per entry would cost far more than the information is worth.

Two limitations, both tracked

This reports the entry’s own provenance, not its subtree’s. A directory whose descendants are less trustworthy than itself will still report its own source, so a Complete/Revalidated directory can contain Cached children. Composition belongs in the roll-up, where it costs one merge rather than an O(subtree) walk per query, and it is not implemented yet (fdu-fka6, fdu-b1ts). Do not read a directory’s provenance as a subtree guarantee.

A completed reconciliation records one clocked StateTransition::Verified for its subtree, including when every entry was unchanged. Consumers of exact commits therefore observe the same provenance movement as readers of this view.

Trait Implementations

impl Clone for Index

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Index

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.