Module sort 

pathlint sort --dry-run — propose a PATH order that satisfies every applicable [[expect]] rule, without touching the real PATH.

Pure: the public entry point sort_path takes the current entries, the expectation set, the merged source catalog, and the current OS, and returns a SortPlan. Callers print it and decide on the exit code.

Read-only by design — PRD §4 forbids PATH mutation. Any future --apply mode would live behind its own subcommand and a flag the user has to pass explicitly.

See PRD §7.8 for the role this plays in the four-role model (R5 — repair, the inverse of R1 resolve order).

Algorithm (0.0.8 MVP)

1. For every PATH entry, find which [source.X] names match it via crate::source_match::find.
2. For every [[expect]] rule whose os filter applies, mark the entries matching its prefer set as “preferred for command”. Entries matching avoid are marked too.
3. Compute a stable reordering: preferred entries float ahead of avoided entries for the same command, while every other entry’s relative order is preserved.
4. Diff the original and sorted vectors to populate moves.

Stability matters: pathlint must not rearrange entries it has no opinion on, so sysadmins reading the diff see only the changes they need to think about.

Examples

use pathlint::config::Config;
use pathlint::os_detect::Os;
use pathlint::path_entry::PathEntry;
use pathlint::sort;

let cfg = Config::default();
let sources = pathlint::catalog::merge_with_user(&cfg.source);
let relations = pathlint::catalog::merge_with_user_relations(&cfg.relations);
let null_env = |_: &str| -> Option<String> { None };
let entries = vec![
    PathEntry::from_raw("/usr/local/bin", null_env),
    PathEntry::from_raw("/usr/bin", null_env),
];
let plan = sort::sort_path(&entries, &cfg.expectations, &sources, &relations, Os::Linux);
// No expectations → no moves proposed.
assert!(plan.moves.is_empty());

Structs

EntryMove

One entry’s movement from old to new index. Only emitted when the entry actually moved; entries that stayed in place do not generate a EntryMove.

SortPlan

Proposed PATH reordering from pathlint sort --dry-run, carrying the original and sorted entries plus the move list.

Enums

SortNote

Non-blocking observation about a [[expect]] rule. The current PATH cannot satisfy prefer (no PATH entry matches any preferred source), so sort cannot fix it by reordering — the user has to install the missing tool or adjust the rule. Surfaced so the human view can include it as an “fyi” line below the diff.

Functions

sort_path

Compute a sort plan. Pure.