stable_which/lib.rs
1#![warn(missing_docs)]
2//! Evaluate binary path stability and find stable PATH candidates.
3//!
4//! This library analyzes binary paths, tags them with observed attributes
5//! (version manager, build output, ephemeral, shim, etc.), judges their
6//! [`Durability`] (whether a path can be pinned into a service definition),
7//! and ranks them to find the most suitable candidate for use in service
8//! registration, configuration files, or scripts.
9//!
10//! # Quick Start
11//!
12//! ```no_run
13//! use stable_which::{find_candidates, rank_candidates, ScoringPolicy};
14//! use std::path::Path;
15//!
16//! let mut candidates = find_candidates(Path::new("jj")).unwrap();
17//! rank_candidates(&mut candidates, ScoringPolicy::SameBinary);
18//! println!("Best: {}", candidates[0].path().display());
19//! ```
20//!
21//! # API layering
22//!
23//! The public surface separates three concerns:
24//!
25//! - [`find_candidates`] / [`find_candidates_with_path_env`] — *discovery only*,
26//! returns candidates in deterministic (PATH discovery) order.
27//! - [`rank_candidates`] — sorts a candidate slice in place by a
28//! [`ScoringPolicy`].
29//! - [`resolve_stable_path`] — the convenience composition of find + rank that
30//! returns the single best candidate.
31
32mod candidate;
33mod durability;
34mod path_analysis;
35
36// Re-export the primary types and functions. The module structure itself is an
37// implementation detail; consumers reference everything from the crate root.
38pub use candidate::{
39 Candidate, Error, PathTag, ScoringPolicy, find_candidates, find_candidates_with_path_env,
40 rank_candidates, resolve_stable_path,
41};
42pub use durability::Durability;