Struct RecencyIndex 

pub struct RecencyIndex { /* private fields */ }

Recency index that normalizes file timestamps relative to repository history

This index builds a mapping of file paths to their last commit timestamps, then normalizes scores to [0.0, 1.0] based on the repository’s min/max timestamps.

Scoring Formula

score = (timestamp - min_ts) / (max_ts - min_ts)

• 1.0: Newest file in the repository
• 0.5: Mid-point between oldest and newest (or neutral fallback)
• 0.0: Oldest file in the repository

Thread Safety

This struct is Send + Sync and can be shared across threads.

Implementations

impl RecencyIndex

pub fn from_repo(root: &Path) -> Result<Self>

Build a recency index from a git repository

Walks all tracked files in the repository and records their last commit timestamps.

Arguments

• root - Path to repository root (or any directory within the repo)

Returns

• Ok(RecencyIndex) - Successfully built index
• Err(GitError::NotARepo) - Path is not a git repository
• Err(GitError::NotFound) - Git binary not in PATH
• Err(GitError) - Other git command failures

Performance

This operation is relatively expensive (O(n) where n = tracked files). Consider caching the index and rebuilding only when the repository changes.

Examples

let index = RecencyIndex::from_repo(Path::new("/path/to/repo"))?;
println!("Indexed {} files", index.file_count());

Errors

Returns GitError when repository discovery or git commands fail, or when the underlying git output is malformed.

pub fn from_timestamps(by_file: HashMap<PathBuf, i64>, repo_root: &Path) -> Self

Create a recency index from explicit timestamp data (for testing)

This constructor allows creating an index without accessing git, useful for deterministic unit tests.

Arguments

• by_file - Map of file paths to Unix epoch timestamps
• repo_root - Repository root path (used for path resolution)

Panics

Panics if by_file is empty (use an empty HashMap to represent an empty repository, which will result in neutral 0.5 scores).

Examples

let timestamps = HashMap::from([
    (PathBuf::from("old.rs"), 1000),
    (PathBuf::from("mid.rs"), 2000),
    (PathBuf::from("new.rs"), 3000),
]);
let index = RecencyIndex::from_timestamps(timestamps, Path::new("/repo"));
assert!(index.score_for_file(Path::new("new.rs")) > index.score_for_file(Path::new("old.rs")));

pub fn score_for_file(&self, path: &Path) -> f32

Compute recency score for a file

Returns a normalized score in [0.0, 1.0] where:

• 1.0: Newest file in repository
• 0.5: Neutral (file not in index, or all files have same timestamp)
• 0.0: Oldest file in repository

Arguments

• path - File path (absolute or relative to repo root)

Returns

Normalized recency score (0.0-1.0)

Fallback Behavior

Returns 0.5 (neutral) when:

• File not found in index
• All files have identical timestamps (min_ts == max_ts)
• Empty repository (no tracked files)

Examples

let index = RecencyIndex::from_repo(Path::new("/repo"))?;

// Absolute path
let score = index.score_for_file(Path::new("/repo/src/main.rs"));

// Relative path (resolved against repo root)
let score = index.score_for_file(Path::new("src/main.rs"));

// File not in index → neutral 0.5
let score = index.score_for_file(Path::new("not_tracked.txt"));
assert_eq!(score, 0.5);

pub fn file_count(&self) -> usize

Get the number of files tracked in this index

pub fn repo_root(&self) -> &Path

Get the repository root path

pub fn timestamp_range(&self) -> Option<(i64, i64)>

Get the timestamp range (min, max) in Unix epoch seconds

Returns None for empty repositories.

Trait Implementations

impl Clone for RecencyIndex

fn clone(&self) -> RecencyIndex

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RecencyIndex

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

Formats the value using the given formatter.