kache 0.16.0

//! Path normalization for cache keys.
//!
//! Purpose: stop machine-local absolute paths from leaking into cache
//! keys. Without this, a build at `/path/A/foo` and a build at
//! `/path/B/foo` produce different cache keys for byte-identical
//! sources — cache hits don't transfer across machines or worktrees,
//! and even relocating a project on the same machine misses
//! everything.
//!
//! ## Why a struct, not just `replace_cwd`
//!
//! Before this module, the cache_key code shipped a one-off
//! `normalize_flags` that did `value.replace(cwd, ".")`. Two failure
//! modes the struct fixes:
//!
//! 1. **Symlink-induced miss** (the e422e55 class). On macOS, `/tmp`
//!    is a symlink to `/private/tmp`. CWD reports `/tmp/build` but
//!    cargo emits `OUT_DIR=/private/tmp/build/...`. Literal string
//!    replace finds no match → path leaks into the key. Canonicalizing
//!    the prefix once at construction time fixes this without paying
//!    a `canonicalize()` per-replacement.
//!
//! 2. **Single-prefix horizon**. CWD is one of several path prefixes
//!    a cache key wants stripped. The struct holds an ordered list of
//!    `(prefix, sentinel)` rules so adding a new one is a one-line
//!    edit, not a new ad-hoc helper.
//!
//! ## Cross-machine contract
//!
//! For shared / remote caches (CI runners, multiple devs hitting the
//! same S3 bucket), key portability requires every machine-local path
//! to map to the same sentinel. Today's rule set covers:
//!
//! | Prefix              | Sentinel        | Why it varies per host |
//! |---------------------|-----------------|------------------------|
//! | workspace root      | `<WORKSPACE>`   | per-checkout location  |
//! | `$CARGO_TARGET_DIR` | `<TARGET>`      | per-user / per-job dir |
//! | `$CARGO_HOME`       | `<CARGO_HOME>`  | usually `~/.cargo`     |
//! | `$RUSTUP_HOME`      | `<RUSTUP_HOME>` | usually `~/.rustup`    |
//! | `$HOME`             | `<HOME>`        | per-user               |
//! | system tempdir      | `<TMPDIR>`      | macOS uses `/var/folders/<random>/T` per user |
//!
//! ## Two consumers, two targets per rule
//!
//! Each rule carries a `key_sentinel` AND a `flag_target`:
//!
//! - [`Self::normalize`] stamps the `key_sentinel` into cache-key INPUTS (env
//!   var values, RUSTFLAGS, etc.). Rules run in most-specific-first order —
//!   first match wins. Explicit configured roots additionally require path
//!   component boundaries, matching rustc's remap behavior. These stay the
//!   stable machine-independent tokens
//!   (`<WORKSPACE>`, `<CARGO_HOME>`, …) that give cross-machine / cross-worktree
//!   key portability.
//! - [`Self::remap_args`] renders the `flag_target` as
//!   `--remap-path-prefix=PREFIX=TARGET` flags for rustc. Targets are
//!   ABSOLUTE, profiler-resolvable paths (`/proc/self/cwd` on Linux,
//!   `/rustc/<hash>`, `/kache/*`) so a cached `.rlib`'s DWARF resolves in
//!   samply / the Firefox Profiler and debuggers without configuration
//!   (kunobi-ninja/kache#480, #485). Flags are emitted in
//!   [`flag_emit_rank`] order (a semantic precedence), not the rule-list
//!   order, so under rustc's last-match-wins a crates.io dep resolves under
//!   `/kache/.cargo` while a workspace member keeps `/proc/self/cwd`.
//!
//! The `flag_target` is not hashed into the rustc key. The default target set is
//! deliberately unkeyed (#399), while the stable count of explicitly
//! configured roots is keyed; portability still comes from `key_sentinel` via
//! `normalize`.
//!
//! What this **still doesn't** cover (separate concerns):
//!
//! - **build.rs-generated paths inside `OUT_DIR`**:
//!   `--remap-path-prefix` only rewrites paths rustc knows about at
//!   compile time. A `private.rs` generated by serde's build.rs may
//!   contain paths internally (rare in practice). Future fixture +
//!   audit if a real-world case shows up.
//! - **Toolchain divergence**: different rustc / linker / SDK versions
//!   produce different output for the same source. Already captured
//!   by `rustc_version` + `linker_id` in the cache key — non-shareable
//!   by design when these differ.
//! - **Sentinel collision**: if a real path string contained
//!   `<WORKSPACE>` literally, replacement would corrupt it. POSIX
//!   paths don't use `<`/`>`; Windows uses them only inside `\\?\`
//!   device-path forms which aren't cache-key inputs. Acceptable risk.
//!
//! ## macOS Unicode normalization (NFC vs NFD)
//!
//! HFS+ historically stored filenames in NFD form (`é` as `e` +
//! combining accent — three UTF-8 bytes); APFS preserves whatever
//! form the API caller used. Env vars set by shells / build tools
//! typically use NFC (`é` as a single codepoint — two UTF-8 bytes).
//! Same character to the eye, **different bytes**.
//!
//! Without normalization, a user `José` would silently lose
//! cross-machine cache sharing while ASCII-named users got it for
//! free — the cache key for their workspace would diverge across
//! tools that disagree on the encoding. We normalize both sides
//! (rule prefixes via [`canonical_string`], input via
//! [`PathNormalizer::normalize`]) to NFC before matching. Same
//! source bytes after normalization → same key.
//!
//! ## Sentinel strategy
//!
//! Each prefix maps to a stable token. Sentinels are angle-bracketed
//! so they can't appear in real path strings. Order matters: longer /
//! more-specific prefixes match first so `<WORKSPACE>` shadows
//! `<HOME>` for users whose workspace lives inside their home dir.
//!
//! ## Leak detection
//!
//! After applying all rules, [`PathNormalizer::normalize`] scans the
//! result for substrings that still look like absolute paths
//! (`/Users/`, `/home/`, `/private/`, drive letters). When found,
//! emits a `tracing::warn!` naming the suspicious value. This is a
//! defense-in-depth check — the relocate e2e phase exists to surface
//! these by failing the build, but the warning gives a faster signal
//! during ad-hoc dev runs without needing to run the full harness.

use std::path::{Path, PathBuf};
use unicode_normalization::UnicodeNormalization;

/// One canonicalized prefix plus the two things it maps to: a stable
/// `key_sentinel` for cache-key inputs, and a resolvable `flag_target`
/// for the DWARF/PDB path rustc bakes into artifacts.
#[derive(Debug, Clone)]
struct Rule {
    prefix: String,
    /// Machine-independent token substituted into cache-key INPUTS by
    /// [`PathNormalizer::normalize`] (`<WORKSPACE>`, `<CARGO_HOME>`, …).
    /// Key portability depends on this; unchanged from the original
    /// single-sentinel design.
    key_sentinel: String,
    /// Source-key owner. Usually identical to `key_sentinel`, except the
    /// process CWD and workspace root need distinct identities even though
    /// rustc remaps both to the same debug-path target.
    source_sentinel: String,
    /// Absolute, profiler-resolvable path injected into rustc
    /// `--remap-path-prefix` by [`PathNormalizer::remap_args`] so the spelling
    /// baked into debug info is resolvable by samply / the Firefox Profiler and
    /// by debuggers (`/proc/self/cwd`, `/rustc/<hash>`, `/kache/*`). Distinct
    /// from `key_sentinel` so debug-info resolvability and cache-key portability
    /// evolve independently (kunobi-ninja/kache#480, #485).
    flag_target: String,
}

/// A user-configured source root that can be represented losslessly in source
/// keys and round-tripped through rustc dep-info.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct ConfiguredSourceRoot {
    pub root: PathBuf,
    pub key_sentinel: String,
    pub depinfo_sentinel: String,
    pub priority: u8,
}

#[derive(Debug, Clone)]
struct ConfiguredSourceRootGroup {
    restore_root: PathBuf,
    aliases: Vec<PathBuf>,
    key_sentinel: String,
    depinfo_sentinel: String,
}

/// Replaces machine-local path prefixes with stable sentinels so
/// cache keys are reproducible across hosts and worktrees.
///
/// Construction is best-effort: prefixes that fail to canonicalize
/// (because the env var isn't set, or the path doesn't exist) are
/// silently dropped. This is intentional — a missing
/// `$CARGO_TARGET_DIR` shouldn't make every cache key generation
/// fail; the worst case is the rule doesn't apply for that build.
#[derive(Debug, Clone)]
pub struct PathNormalizer {
    rules: Vec<Rule>,
    /// Number of validated `[paths].base_dirs` entries. Keep this separate
    /// from the expanded/deduplicated rules: two configured symlinks may
    /// resolve to the same prefix without ceasing to be two configured slots.
    configured_base_dir_count: usize,
    /// Existing configured roots grouped by stable slot. The lexical root is
    /// always emitted first for dep-info expansion; canonical/Windows aliases
    /// are accepted only while relativizing producer paths.
    configured_source_root_groups: Vec<ConfiguredSourceRootGroup>,
    /// Lexical consumer root for automatic owners whose rule list also carries
    /// canonical, Unicode, Windows, or 8.3 aliases. Key/remap matching may use
    /// any alias; dep-info expansion must return to this designated spelling.
    source_restore_roots: Vec<(String, PathBuf)>,
    /// Plain env vars and scoped `rustc_crate_name:VAR` assertions opted into
    /// path-only cache-key normalization. See
    /// [`crate::config::Config::path_only_env_vars`].
    path_only_env_vars: Vec<String>,
}

impl PathNormalizer {
    /// Build a normalizer from the current process environment plus
    /// an optional explicit workspace root.
    ///
    /// Rule order is most-specific first, so when prefixes nest
    /// (workspace inside `$HOME`, target dir inside workspace) the
    /// inner prefix wins:
    ///
    /// 1. current working directory → `<WORKSPACE>`
    /// 2. `workspace_root` (if provided) → `<WORKSPACE>`
    /// 3. `$CARGO_TARGET_DIR` → `<TARGET>`
    /// 4. `$CARGO_HOME` (or default `~/.cargo`) → `<CARGO_HOME>`
    /// 5. `$RUSTUP_HOME` (or default `~/.rustup`) → `<RUSTUP_HOME>`
    /// 6. `$HOME` → `<HOME>`
    /// 7. system tempdir (`std::env::temp_dir()`) → `<TMPDIR>`
    ///
    /// Rule 1 is what rewrites rustc's DWARF `DW_AT_comp_dir` — rustc
    /// records its working directory there verbatim, and the other
    /// rules only rewrite it if one's prefix matches the CWD exactly.
    /// Without rule 1 a debug build leaks the build path through
    /// `comp_dir` (and any dSYM derived from it). kache runs as
    /// RUSTC_WRAPPER with no `chdir`, so the wrapper's CWD is the CWD
    /// rustc records. For a workspace member it is more specific than
    /// `workspace_root` (the repo root); for a single package they
    /// coincide and the dedup below collapses them.
    ///
    /// Tempdir lands last because it can be unrelated to user paths
    /// (`/tmp` on Linux, `/var/folders/.../T` on macOS) — it's
    /// purely for relocate-style scenarios where build artifacts
    /// flow through tempdirs.
    pub fn from_env(workspace_root: Option<&Path>) -> Self {
        let mut rules = Vec::new();
        let mut source_restore_roots = Vec::new();

        // User-declared base dir (`KACHE_BASE_DIR`, the analog of ccache's
        // `CCACHE_BASEDIR`). Highest priority — an explicit prefix the
        // user knows should be stripped so the key is independent of the
        // checkout location. Covers paths the auto-derived rules below
        // can't see (container mounts, generated-file env-deps that point
        // outside the workspace, etc.).
        let legacy_base_dir = std::env::var_os("KACHE_BASE_DIR");
        push_legacy_base_dir_rules(
            &mut rules,
            &mut source_restore_roots,
            legacy_base_dir.as_deref(),
        );

        if let Ok(current_dir) = std::env::current_dir() {
            push_path_rule_aliases(
                &mut rules,
                &mut source_restore_roots,
                &current_dir,
                "<WORKSPACE>",
                "<CWD>",
            );
        }

        if let Some(workspace_root) = workspace_root {
            push_path_rule_aliases(
                &mut rules,
                &mut source_restore_roots,
                workspace_root,
                "<WORKSPACE>",
                "<WORKSPACE>",
            );
        }

        if let Some(target_dir) = std::env::var_os("CARGO_TARGET_DIR") {
            push_path_rule_aliases(
                &mut rules,
                &mut source_restore_roots,
                Path::new(&target_dir),
                "<TARGET>",
                "<TARGET>",
            );
        }

        // CARGO_HOME defaults to $HOME/.cargo if not set; honor that
        // so users with the default layout still get the substitution.
        let cargo_home = std::env::var_os("CARGO_HOME")
            .map(PathBuf::from)
            .or_else(|| dirs::home_dir().map(|h| h.join(".cargo")));
        push_rule_with_variants(
            &mut rules,
            cargo_home.and_then(|p| canonical_string(&p)),
            "<CARGO_HOME>",
        );

        // Same default-fallback story for RUSTUP_HOME. rustup paths
        // appear in -L flags and toolchain refs — without this rule,
        // Dev A's `~alice/.rustup` and Dev B's `~bob/.rustup` would
        // produce different keys for byte-identical sources.
        let rustup_home = std::env::var_os("RUSTUP_HOME")
            .map(PathBuf::from)
            .or_else(|| dirs::home_dir().map(|h| h.join(".rustup")));
        push_rule_with_variants(
            &mut rules,
            rustup_home.and_then(|p| canonical_string(&p)),
            "<RUSTUP_HOME>",
        );

        push_rule_with_variants(
            &mut rules,
            dirs::home_dir().and_then(|p| canonical_string(&p)),
            "<HOME>",
        );

        // Windows-specific rules: cargo / rustup paths often live
        // under %APPDATA% / %LOCALAPPDATA% (e.g. CARGO_HOME defaults
        // to %USERPROFILE%\.cargo but tools like rustup-init may
        // also stash state in %LOCALAPPDATA%\rustup). %PROGRAMFILES%
        // covers MSVC / SDK locations that flow into native-link
        // search paths. Each is added as its own sentinel so cross-
        // dev caches don't leak per-user paths.
        for (env_key, sentinel) in [
            ("APPDATA", "<APPDATA>"),
            ("LOCALAPPDATA", "<LOCALAPPDATA>"),
            ("PROGRAMFILES", "<PROGRAMFILES>"),
        ] {
            push_rule_with_variants(
                &mut rules,
                std::env::var_os(env_key).and_then(|v| canonical_string(Path::new(&v))),
                sentinel,
            );
        }

        // System tempdir — varies wildly across hosts (per-user random
        // segment on macOS like `/var/folders/1z/.../T`). Build
        // artifacts from build.rs scripts often pass through tempdirs
        // for intermediate output.
        push_rule_with_variants(
            &mut rules,
            canonical_string(&std::env::temp_dir()),
            "<TMPDIR>",
        );

        // De-dupe: if (e.g.) CARGO_HOME == workspace_root, the second
        // entry would never fire. Keep order stable so the first-listed
        // sentinel wins for identical prefixes. Use a *global* keep-first
        // dedup rather than `dedup_by` (adjacent-only): two sources that
        // share a canonical form expand to interleaved variant blocks
        // (e.g. on Windows `[canon_a, \a]` then `[canon_b, \b]`), so the
        // duplicate prefixes are not adjacent and `dedup_by` would miss them.
        let mut seen = std::collections::HashSet::new();
        rules.retain(|r| seen.insert(r.prefix.clone()));

        Self {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots,
            path_only_env_vars: Vec::new(),
        }
    }

    /// Opt plain env vars or scoped `rustc_crate_name:VAR` assertions into
    /// path-only key normalization, e.g. from `[cache] path_only_env_vars`.
    pub fn with_path_only_env_vars(mut self, vars: Vec<String>) -> Self {
        self.path_only_env_vars = vars;
        self
    }

    /// Add Cargo's effective target directory derived from the rustc argv.
    ///
    /// `CARGO_TARGET_DIR` is often unset, especially for Cargo's default
    /// `<workspace>/target`. Dependency crates are compiled with their own
    /// package directory as cwd, so the workspace root cannot always be
    /// verified from cwd either. The rustc output layout still identifies the
    /// target directory exactly; adding it here keeps build-script generated
    /// sources portable without trusting an inferred workspace root.
    pub(crate) fn with_target_dir(mut self, target_dir: Option<&Path>) -> Self {
        let Some(target_dir) = target_dir else {
            return self;
        };

        let mut target_rules = Vec::new();
        push_path_rule_aliases(
            &mut target_rules,
            &mut self.source_restore_roots,
            target_dir,
            "<TARGET>",
            "<TARGET>",
        );

        // Keep the same semantic order as rustc's last-match-wins remap set:
        // workspace/configured/Cargo-home owners outrank TARGET, while user
        // dirs and TMPDIR must not consume an external target first.
        let target_rank = flag_emit_rank("<TARGET>");
        let insert_at = self
            .rules
            .iter()
            .position(|rule| flag_emit_rank(&rule.key_sentinel) < target_rank)
            .unwrap_or(self.rules.len());
        self.rules.splice(insert_at..insert_at, target_rules);

        let mut seen = std::collections::HashSet::new();
        self.rules.retain(|rule| seen.insert(rule.prefix.clone()));
        self
    }

    /// Add the validated `[paths].base_dirs` rule set.
    ///
    /// Entries are sorted by their lexical spelling before sentinel assignment,
    /// so TOML list order is irrelevant. Every entry gets a distinct stable
    /// `<BASE_DIR_N>` key sentinel and `/kache/base-dir-N` compiler target.
    /// Within this explicit list, longer prefixes are placed first so an
    /// overlapping child root wins over its parent.
    pub fn with_base_dirs(mut self, base_dirs: &[String]) -> Self {
        let (configured, mut extra_rules) = configured_base_dir_rules(base_dirs);
        self.configured_base_dir_count = configured.len();

        let legacy_prefixes: std::collections::HashSet<String> = self
            .rules
            .iter()
            .filter(|rule| rule.key_sentinel == "<BASE_DIR>")
            .map(|rule| rule.prefix.clone())
            .collect();

        // Preserve the legacy KACHE_BASE_DIR sentinel if the new list repeats
        // exactly that prefix. For all other configured entries, explicit
        // longest-prefix precedence applies ahead of auto-detected rules.
        extra_rules.retain(|rule| !legacy_prefixes.contains(&rule.prefix));
        extra_rules.sort_by(|left, right| {
            right
                .prefix
                .len()
                .cmp(&left.prefix.len())
                .then_with(|| left.prefix.cmp(&right.prefix))
                .then_with(|| left.key_sentinel.cmp(&right.key_sentinel))
        });
        extra_rules.append(&mut self.rules);
        let mut seen = std::collections::HashSet::new();
        extra_rules.retain(|rule| seen.insert(rule.prefix.clone()));
        self.rules = extra_rules;
        self.configured_source_root_groups = configured
            .iter()
            .enumerate()
            .filter_map(|(index, lexical)| {
                let restore_root = PathBuf::from(lexical);
                if !restore_root.exists() {
                    return None;
                }
                let key_sentinel = configured_base_dir_sentinel(index);
                if self
                    .source_rule_for_path(&restore_root)
                    .is_none_or(|winner| winner.key_sentinel != key_sentinel)
                {
                    return None;
                }
                let depinfo_sentinel = format!("__kache_base_dir_{index}__/");
                let aliases = self
                    .rules
                    .iter()
                    .filter(|rule| rule.key_sentinel == key_sentinel)
                    .filter(|rule| is_native_configured_path(&rule.prefix))
                    .filter(|rule| rule.prefix != *lexical)
                    .map(|rule| PathBuf::from(&rule.prefix))
                    .filter(|alias| alias.exists())
                    .collect();
                Some(ConfiguredSourceRootGroup {
                    restore_root,
                    aliases,
                    key_sentinel,
                    depinfo_sentinel,
                })
            })
            .collect();
        self
    }

    /// Number of machine-independent configured base-dir sentinels. This is
    /// safe to fold into a cache key: it distinguishes configured from
    /// unconfigured clients without hashing the machine-local prefixes.
    pub fn configured_base_dir_count(&self) -> usize {
        self.configured_base_dir_count
    }

    /// The configured path-only env-var allowlist and scoped assertions
    /// (excluding built-in OUT_DIR handling).
    pub fn path_only_env_vars(&self) -> &[String] {
        &self.path_only_env_vars
    }

    /// The raw (un-normalized) machine-local prefixes this normalizer replaces
    /// with sentinels, including all Windows shape variants.
    ///
    /// This is exactly the set of prefixes that [`Self::normalize`] erases from
    /// cache-key inputs and [`Self::remap_args`] tells rustc to erase from debug
    /// info. When rustc remap injection is disabled
    /// (`KACHE_RUSTC_PATH_NORMALIZE=0`) those prefixes are baked into DWARF
    /// verbatim, so the cache key must fold them back to stay path-local — see
    /// [`crate::cache_key::fold_unremapped_path_identity`]. Returning the actual
    /// rule set (rather than a hand-maintained subset) keeps that fold complete
    /// as new rules are added (`<TARGET>`, `<BASE_DIR>`, the Windows roots, …).
    pub(crate) fn raw_prefixes(&self) -> impl Iterator<Item = &str> {
        self.rules
            .iter()
            .map(|r| r.prefix.as_str())
            .filter(|p| !p.is_empty())
    }

    /// Existing configured roots with raw OS-path identity preserved.
    ///
    /// Non-existent cross-platform entries remain useful for flag remapping
    /// but cannot contain a source in this invocation, so they are omitted.
    /// Each returned spelling is an actual winning rustc remap rule. Do not
    /// canonicalize or merge them: a configured symlink and its target may be
    /// distinct configured slots, and dep-info must retain that ownership.
    pub(crate) fn depinfo_source_roots(&self) -> Vec<ConfiguredSourceRoot> {
        let mut groups = self.configured_source_root_groups.clone();
        for source_sentinel in [
            "<CWD>",
            "<WORKSPACE>",
            "<TARGET>",
            "<CARGO_HOME>",
            "<BASE_DIR>",
            "<RUSTUP_HOME>",
            "<HOME>",
            "<APPDATA>",
            "<LOCALAPPDATA>",
            "<PROGRAMFILES>",
            "<TMPDIR>",
        ] {
            let owned_rules = self
                .rules
                .iter()
                .filter(|rule| rule.source_sentinel == source_sentinel)
                .filter(|rule| is_native_configured_path(&rule.prefix))
                .filter(|rule| Path::new(&rule.prefix).exists())
                .collect::<Vec<_>>();
            let designated = self
                .source_restore_roots
                .iter()
                .find(|(sentinel, _)| sentinel == source_sentinel)
                .map(|(_, root)| root.clone());
            let restore_root = designated
                .and_then(|root| {
                    self.source_rule_for_path(&root)
                        .is_some_and(|rule| rule.source_sentinel == source_sentinel)
                        .then_some(root)
                })
                .or_else(|| {
                    owned_rules.iter().find_map(|rule| {
                        let root = PathBuf::from(&rule.prefix);
                        self.source_rule_for_path(&root)
                            .is_some_and(|winner| winner.source_sentinel == source_sentinel)
                            .then_some(root)
                    })
                });
            if let Some(restore_root) = restore_root {
                let restore_spelling = restore_root.as_os_str();
                let aliases = owned_rules
                    .iter()
                    .filter(|rule| {
                        self.source_rule_for_path(Path::new(&rule.prefix))
                            .is_some_and(|winner| winner.source_sentinel == source_sentinel)
                    })
                    .filter(|rule| std::ffi::OsStr::new(&rule.prefix) != restore_spelling)
                    .map(|rule| PathBuf::from(&rule.prefix))
                    .collect();
                let Some(key_sentinel) = self
                    .source_rule_for_path(&restore_root)
                    .map(|rule| rule.key_sentinel.clone())
                else {
                    continue;
                };
                groups.push(ConfiguredSourceRootGroup {
                    restore_root,
                    aliases,
                    key_sentinel,
                    depinfo_sentinel: depinfo_sentinel_for_source(source_sentinel)
                        .expect("listed source roots have dep-info sentinels"),
                });
            }
        }
        groups.sort_by_key(|group| {
            let longest = std::iter::once(&group.restore_root)
                .chain(group.aliases.iter())
                .map(|root| root.as_os_str().len())
                .max()
                .unwrap_or_default();
            std::cmp::Reverse((flag_emit_rank(&group.key_sentinel), longest))
        });
        groups
            .into_iter()
            .flat_map(|group| {
                let key_sentinel = group.key_sentinel;
                let depinfo_sentinel = group.depinfo_sentinel;
                std::iter::once(group.restore_root)
                    .chain(group.aliases)
                    .map(move |root| ConfiguredSourceRoot {
                        root,
                        key_sentinel: key_sentinel.clone(),
                        depinfo_sentinel: depinfo_sentinel.clone(),
                        priority: flag_emit_rank(&key_sentinel),
                    })
            })
            .collect()
    }

    /// Lossless source identity matching the rule rustc will actually apply.
    ///
    /// `remap_args` is last-match-wins by semantic rank, then prefix length.
    /// Reusing that exact ordering prevents a key from collapsing paths that
    /// rustc embeds differently (notably nested target/workspace roots).
    /// Non-UTF-8 or unmatched paths return `None` so callers can bind an opaque
    /// machine-local identity instead of guessing.
    pub(crate) fn source_path_identity(&self, path: &Path) -> Option<Vec<u8>> {
        let input = path.as_os_str().to_str()?;
        let winner = self.source_rule_for_path(path)?;
        depinfo_sentinel_for_source(&winner.source_sentinel)?;
        let remainder = input.strip_prefix(&winner.prefix)?;
        let remainder = remainder
            .strip_prefix('/')
            .or_else(|| remainder.strip_prefix('\\'))
            .unwrap_or(remainder);
        let mut identity = winner.source_sentinel.as_bytes().to_vec();
        if !remainder.is_empty() {
            identity.push(b'/');
            identity.extend_from_slice(remainder.as_bytes());
        }
        Some(identity)
    }

    fn source_rule_for_path<'a>(&'a self, path: &Path) -> Option<&'a Rule> {
        let input = path.as_os_str().to_str()?;
        self.rules
            .iter()
            .filter(|rule| !rule.prefix.is_empty())
            .filter_map(|rule| {
                input.strip_prefix(&rule.prefix)?;
                if !configured_prefix_boundaries_match(input, 0, rule.prefix.len(), &rule.prefix) {
                    return None;
                }
                Some((flag_emit_rank(&rule.key_sentinel), rule.prefix.len(), rule))
            })
            .max_by_key(|(rank, prefix_len, _)| (*rank, *prefix_len))
            .map(|(_, _, rule)| rule)
    }

    /// Add the toolchain-source rule that re-virtualizes rust std/core paths to
    /// the upstream `/rustc/<commit-hash>/...` form.
    ///
    /// When the `rust-src` rustup component is installed, rustc de-virtualizes
    /// the prebuilt std's `/rustc/<hash>/library/...` paths to the local
    /// `{sysroot}/lib/rustlib/src/rust/library/...` in the debug info of
    /// user-compiled generic instantiations. That local path is unresolvable to
    /// a profiler. Remapping it back to `/rustc/<commit-hash>` restores exactly
    /// the form samply / the Firefox Profiler / rust-gdb already fetch from
    /// github.com/rust-lang/rust (kunobi-ninja/kache#485).
    ///
    /// The rule is inserted after explicit `<BASE_DIR_N>` rules but before the
    /// automatic rules. This keeps key-side first-match precedence aligned with
    /// [`Self::remap_args`]: an explicit configured root wins if it overlaps
    /// rust-src; otherwise `<RUST_SRC>` wins over `<RUSTUP_HOME>`. No-op when
    /// rust-src isn't installed (the prefix fails to canonicalize) or the commit
    /// hash is unavailable (locally-built rustc): std paths then stay virtual.
    ///
    /// Must be applied identically on the cache-key side ([`crate::wrapper`]) and
    /// the injection side ([`crate::compiler::rustc`]) — same lockstep contract
    /// as the rest of the rule set.
    pub fn with_rust_src_rule(mut self, sysroot: Option<&Path>, commit_hash: Option<&str>) -> Self {
        let (Some(sysroot), Some(hash)) = (sysroot, commit_hash) else {
            return self;
        };
        let rust_src = sysroot.join("lib").join("rustlib").join("src").join("rust");
        let Some(prefix) = canonical_string(&rust_src) else {
            return self;
        };
        let flag_target = format!("/rustc/{hash}");

        // Build the rule (+ Windows variants) into a scratch vec, then insert
        // it immediately after all explicit configured roots.
        let mut rust_src_rules = Vec::new();
        push_rule_with_variants_target(
            &mut rust_src_rules,
            Some(prefix),
            "<RUST_SRC>",
            &flag_target,
        );
        let insert_at = self
            .rules
            .iter()
            .position(|rule| configured_base_dir_index(&rule.key_sentinel).is_none())
            .unwrap_or(self.rules.len());
        self.rules.splice(insert_at..insert_at, rust_src_rules);

        // Re-run the global keep-first dedup (mirrors from_env): the rust-src
        // prefix is deeper than the rustup prefix so they don't collide, but a
        // Windows variant might duplicate an existing entry.
        let mut seen = std::collections::HashSet::new();
        self.rules.retain(|r| seen.insert(r.prefix.clone()));
        self
    }

    /// A normalizer with no rules — leaves every input unchanged.
    /// Used in tests and as a sentinel "no normalization configured"
    /// state in code paths where the env-derived constructor isn't
    /// applicable.
    ///
    /// `#[allow(dead_code)]` because the only consumer today is the
    /// test module; production code always builds via `from_env`.
    /// Kept as part of the public surface so future callers (e.g.
    /// integration tests of cache_key with deterministic inputs)
    /// don't have to construct `PathNormalizer` via `from_env` and
    /// pull in the host's actual env state.
    #[allow(dead_code)]
    pub fn empty() -> Self {
        Self {
            rules: Vec::new(),
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        }
    }

    /// Replace every known prefix in `s` with its sentinel.
    ///
    /// Operates on raw strings (not [`Path`]) because cache-key
    /// inputs are typically values from shell commands and env vars
    /// that may contain paths embedded in larger strings (e.g.
    /// `-L /home/x/lib -L /home/x/build/deps`). Automatic rules keep their
    /// historical literal-substring behavior. Explicit `[paths].base_dirs`
    /// rules require path-token and path-component boundaries, matching
    /// rustc's remap behavior. Rules apply in declaration order, so the first
    /// match for a given byte range wins.
    ///
    /// **Pure substring replace, modulo Unicode normalization.**
    /// Earlier drafts canonicalized the input to handle Windows
    /// separator and drive-letter case differences. That worked for
    /// cache-key hashing but had a side effect: parts of the input
    /// that DIDN'T match a rule still got their separators flipped.
    /// For Windows compatibility we instead store MULTIPLE VARIANTS
    /// of each prefix (forward/back slash, upper/lower drive) in
    /// [`Self::from_env`] — see that method's docs. The matching
    /// here is a byte-literal pass over every variant.
    ///
    /// **Unicode normalization to NFC** is applied to the input
    /// before matching, because rule prefixes are stored in NFC
    /// (see [`canonical_string`]). This handles the macOS HFS+/APFS
    /// case where filesystem APIs may return paths in NFD (`é` as
    /// `e` + combining accent) while env vars set by other tools
    /// use NFC (`é` as a single codepoint). Same character to the
    /// eye, different bytes — without this, a user `José` would
    /// silently lose cross-machine cache sharing while ASCII-named
    /// users got it for free. NFC is semantic-preserving for path
    /// strings (composed and decomposed forms are equivalent path
    /// representations); the normalize step is a no-op on inputs
    /// that are already NFC (the common case).
    pub fn normalize<S: AsRef<str>>(&self, s: S) -> String {
        let mut out: String = s.as_ref().nfc().collect();
        for rule in &self.rules {
            if rule.prefix.is_empty() {
                continue;
            }
            out = if configured_base_dir_index(&rule.key_sentinel).is_some() {
                replace_configured_path_prefix(&out, &rule.prefix, &rule.key_sentinel)
            } else {
                out.replace(&rule.prefix, &rule.key_sentinel)
            };
        }
        warn_if_path_leaked(&out);
        out
    }

    /// Render the rule set as `--remap-path-prefix=PREFIX=TARGET` arguments for
    /// a rustc invocation. Unlike [`Self::normalize`] (which stamps the
    /// machine-independent `key_sentinel` into cache-key inputs), this emits the
    /// resolvable `flag_target`, so the paths baked into DWARF/PDB —
    /// `DW_AT_comp_dir`, `decl_file`, `#[track_caller]`, `file!()`, panic
    /// locations — become spellings profilers and debuggers can resolve
    /// (kunobi-ninja/kache#480, #485).
    ///
    /// **Order is by semantic precedence, not the rule-list order.** rustc
    /// applies `--remap-path-prefix` with last-match-wins and rewrites only the
    /// single winning prefix (the matched head is replaced, the suffix
    /// preserved — mappings are not chained). We exploit that: when prefixes
    /// nest, the flag emitted LAST wins, so we sort by [`flag_emit_rank`]
    /// ascending and let the highest-rank container win.
    ///
    /// The load-bearing case is a crates.io dependency: cargo runs rustc with
    /// its CWD set to `$CARGO_HOME/registry/src/<reg>/<crate>-<ver>`, so the
    /// `<WORKSPACE>` (cwd) rule's prefix is *inside* the `<CARGO_HOME>` rule's
    /// prefix. Ranking `<CARGO_HOME>` above `<WORKSPACE>` makes the dep's
    /// `comp_dir` map to `/kache/.cargo/registry/src/<reg>/<crate>-<ver>` (which
    /// samply resolves to crates.io) instead of `/proc/self/cwd` — no separate
    /// path-composition pass needed. A workspace member (not under
    /// `$CARGO_HOME`) still maps to `/proc/self/cwd`. Same idea puts `<RUST_SRC>`
    /// above `<RUSTUP_HOME>` so std sources become `/rustc/<hash>/...`.
    pub fn remap_args(&self) -> Vec<String> {
        // Stable-sort by ascending rank so the highest-precedence container is
        // emitted LAST and wins under rustc's last-match-wins. Stable keeps the
        // relative order of same-rank rules (e.g. a sentinel's Windows shape
        // variants), which is harmless since they map to the same target.
        let mut ordered: Vec<&Rule> = self.rules.iter().filter(|r| !r.prefix.is_empty()).collect();
        // Primary: semantic rank (higher wins, emitted later). Secondary: prefix
        // length ascending, so within a rank the LONGER (more-specific) prefix is
        // emitted last and wins. Without the length tiebreak, the two `<WORKSPACE>`
        // rules (cwd and the shallower workspace root, same rank) would let the
        // repo root win for a workspace member, mapping `/repo/crates/foo/…` via
        // `/repo` to `/proc/self/cwd/crates/foo/…` — a doubled, non-existent path
        // once `/proc/self/cwd` resolves to the member's real cwd.
        ordered.sort_by_key(|r| (flag_emit_rank(&r.key_sentinel), r.prefix.len()));
        ordered
            .into_iter()
            .map(|r| format!("--remap-path-prefix={}={}", r.prefix, r.flag_target))
            .collect()
    }
}

/// Replace an absolute configured root only at path-component boundaries.
/// Cache-key inputs may contain paths inside flags or structured strings,
/// hence the accepted left delimiters and joined flags. The right boundary is
/// syntax-aware: a backslash separates Windows paths but is a literal byte in
/// POSIX paths.
fn replace_configured_path_prefix(input: &str, prefix: &str, replacement: &str) -> String {
    let mut out = String::with_capacity(input.len());
    let mut copied_until = 0;
    let mut search_from = 0;

    while let Some(relative) = input[search_from..].find(prefix) {
        let start = search_from + relative;
        let end = start + prefix.len();
        if configured_prefix_boundaries_match(input, start, end, prefix) {
            out.push_str(&input[copied_until..start]);
            out.push_str(replacement);
            copied_until = end;
            search_from = end;
        } else {
            // Absolute configured prefixes begin with ASCII (`/`, `\\`, or a
            // drive letter), so advancing one byte remains a char boundary.
            search_from = start + 1;
        }
    }
    out.push_str(&input[copied_until..]);
    out
}

fn configured_prefix_boundaries_match(input: &str, start: usize, end: usize, prefix: &str) -> bool {
    if !is_windows_absolute_path(prefix) && follows_windows_drive_prefix(input, start) {
        return false;
    }
    let left = if start == 0 {
        true
    } else {
        let before = &input[..start];
        before.ends_with("-I")
            || before.ends_with("-L")
            || before.ends_with("-F")
            || before.ends_with("-B")
            || before.chars().next_back().is_some_and(|ch| {
                ch.is_whitespace()
                    || ch == '\u{1f}'
                    || matches!(
                        ch,
                        '=' | ':' | ';' | ',' | '"' | '\'' | '(' | '[' | '{' | '@'
                    )
            })
    };
    let windows = is_windows_absolute_path(prefix);
    let prefix_has_trailing_separator =
        prefix.ends_with('/') || (windows && prefix.ends_with('\\'));
    let right = end == input.len()
        || prefix_has_trailing_separator
        || input[end..]
            .chars()
            .next()
            .is_some_and(|ch| ch == '/' || (windows && ch == '\\'));
    left && right
}

fn follows_windows_drive_prefix(input: &str, start: usize) -> bool {
    if start < 2 {
        return false;
    }
    let bytes = input.as_bytes();
    if bytes[start - 1] != b':' || !bytes[start - 2].is_ascii_alphabetic() {
        return false;
    }
    let lead = &input[..start - 2];
    lead.is_empty()
        || lead.ends_with("-I")
        || lead.ends_with("-L")
        || lead.ends_with("-F")
        || lead.ends_with("-B")
        || lead.chars().next_back().is_some_and(|ch| {
            ch.is_whitespace()
                || ch == '\u{1f}'
                || matches!(
                    ch,
                    '=' | ':' | ';' | ',' | '"' | '\'' | '(' | '[' | '{' | '@'
                )
        })
}

/// Emission precedence for [`PathNormalizer::remap_args`]: lower rank is emitted
/// FIRST, so higher-rank rules win under rustc's last-match-wins when prefixes
/// nest. This is a SEMANTIC precedence, not "most specific wins" — a crates.io
/// dep's CWD is more specific than `$CARGO_HOME` yet `<CARGO_HOME>` must win so
/// the dep resolves to crates.io (see [`PathNormalizer::remap_args`]).
///
/// High rank (wins) → low: configured `<BASE_DIR_N>` > `<RUST_SRC>` >
/// `<CARGO_HOME>` > `<BASE_DIR>` > `<WORKSPACE>` > `<TARGET>` >
/// `<RUSTUP_HOME>` > `<HOME>`/Windows-user-dirs > `<TMPDIR>`. Explicit roots
/// lead so their key and artifact mappings select the same winner. `<TARGET>`
/// below `<WORKSPACE>` means the default `target/` (which
/// sits inside the workspace) maps under `/proc/self/cwd/target/...` — still
/// kernel-resolvable — while an out-of-workspace `$CARGO_TARGET_DIR` (matched by
/// `<TARGET>` alone) maps to `/kache/target`. This ordering only affects
/// injected debug-info spellings; the cache-key `normalize()` side is unaffected.
fn flag_emit_rank(key_sentinel: &str) -> u8 {
    if configured_base_dir_index(key_sentinel).is_some() {
        // Explicit configured roots win on both the key side and the emitted
        // rustc side. Keeping those winners aligned prevents identical keys
        // from producing different `file!()`/DWARF bytes when a configured
        // root overlaps CARGO_HOME or RUST_SRC.
        return 8;
    }
    match key_sentinel {
        "<TMPDIR>" => 0,
        "<HOME>" | "<APPDATA>" | "<LOCALAPPDATA>" | "<PROGRAMFILES>" => 1,
        "<RUSTUP_HOME>" => 2,
        "<TARGET>" => 3,
        "<WORKSPACE>" => 4,
        "<BASE_DIR>" => 5,
        "<CARGO_HOME>" => 6,
        "<RUST_SRC>" => 7,
        // Unknown sentinel: mid-rank so a future addition still emits, and its
        // author is nudged to place it explicitly.
        _ => 4,
    }
}

/// Expand validated configured roots into stable, path-shape-aware rules.
///
/// Lexical spellings are reserved before canonical aliases are considered.
/// Otherwise `/a-link -> /z-real` could steal the exact `/z-real` spelling
/// from a second configured entry and make sentinel assignment depend on
/// whether the symlink exists on this host.
fn configured_base_dir_rules(base_dirs: &[String]) -> (Vec<String>, Vec<Rule>) {
    let mut configured = base_dirs.to_vec();
    configured.sort();
    configured.dedup();
    // Production configuration rejects filesystem roots. Keep this builder
    // fail-safe for direct/test callers too: mapping `/` or `C:/` would erase
    // every absolute-path distinction and cannot be safely represented in
    // dep-info with whole-string replacement.
    configured.retain(|path| !is_filesystem_root_prefix(path));

    let mut lexical_rules = Vec::new();
    for (index, path) in configured.iter().enumerate() {
        push_configured_base_dir_rule(&mut lexical_rules, path.nfc().collect(), index);
    }
    let reserved_lexical: std::collections::HashSet<String> = lexical_rules
        .iter()
        .map(|rule| rule.prefix.clone())
        .collect();

    let mut alias_rules = Vec::new();
    for (index, path) in configured.iter().enumerate() {
        let lexical: String = path.nfc().collect();
        // Shared configs may contain roots for another OS. Keep those lexical
        // and inert: on Windows, for example, `/work` is root-relative and
        // canonicalizing it could manufacture a `C:\\work` alias that was
        // never configured.
        if !is_native_configured_path(path) {
            continue;
        }
        let Ok(canonical) = Path::new(path).canonicalize() else {
            continue;
        };
        for canonical in os_path_spellings(&canonical) {
            if canonical == lexical {
                continue;
            }
            let mut candidates = Vec::new();
            push_configured_base_dir_rule(&mut candidates, canonical, index);
            candidates.retain(|rule| !reserved_lexical.contains(&rule.prefix));
            alias_rules.extend(candidates);
        }
    }

    lexical_rules.extend(alias_rules);
    lexical_rules.sort_by(|left, right| {
        right
            .prefix
            .len()
            .cmp(&left.prefix.len())
            .then_with(|| left.prefix.cmp(&right.prefix))
            .then_with(|| left.key_sentinel.cmp(&right.key_sentinel))
    });
    let mut seen = std::collections::HashSet::new();
    lexical_rules.retain(|rule| seen.insert(rule.prefix.clone()));
    (configured, lexical_rules)
}

fn push_configured_base_dir_rule(rules: &mut Vec<Rule>, prefix: String, index: usize) {
    let sentinel = configured_base_dir_sentinel(index);
    let target = configured_base_dir_target(index);
    if prefix.is_empty() {
        return;
    }
    rules.push(Rule {
        prefix: prefix.clone(),
        key_sentinel: sentinel.clone(),
        source_sentinel: sentinel.clone(),
        flag_target: target.clone(),
    });

    // Config entries are host-independent: expand variants according to the
    // entry's syntax, not the OS running kache. In particular, `/snap` must not
    // gain a `\snap` alias merely because the client runs on Windows.
    if is_windows_absolute_path(&prefix) {
        push_slash_and_case_variants(rules, &prefix, &sentinel, &sentinel, &target);
        if let Some(short) = short_path_name(&prefix)
            && short != prefix
        {
            rules.push(Rule {
                prefix: short.clone(),
                key_sentinel: sentinel.clone(),
                source_sentinel: sentinel.clone(),
                flag_target: target.clone(),
            });
            push_slash_and_case_variants(rules, &short, &sentinel, &sentinel, &target);
        }
    }
}

fn is_windows_absolute_path(path: &str) -> bool {
    let bytes = path.as_bytes();
    (bytes.len() >= 3
        && bytes[0].is_ascii_alphabetic()
        && bytes[1] == b':'
        && matches!(bytes[2], b'/' | b'\\'))
        || path.starts_with("//")
        || path.starts_with(r"\\")
}

fn is_native_configured_path(path: &str) -> bool {
    is_native_configured_path_for(path, cfg!(windows))
}

fn is_native_configured_path_for(path: &str, windows_host: bool) -> bool {
    if windows_host {
        is_windows_absolute_path(path)
    } else {
        path.starts_with('/') && !is_windows_absolute_path(path)
    }
}

/// Prefix/target pairs shared with the C/C++ compiler path mapper.
pub(crate) fn configured_base_dir_prefix_maps(base_dirs: &[String]) -> Vec<(String, String)> {
    configured_base_dir_rules(base_dirs)
        .1
        .into_iter()
        .map(|rule| (rule.prefix, rule.flag_target))
        .collect()
}

pub(crate) fn configured_base_dir_sentinel(index: usize) -> String {
    format!("<BASE_DIR_{index}>")
}

pub(crate) fn configured_base_dir_target(index: usize) -> String {
    format!("/kache/base-dir-{index}")
}

fn configured_base_dir_index(sentinel: &str) -> Option<usize> {
    sentinel
        .strip_prefix("<BASE_DIR_")?
        .strip_suffix('>')?
        .parse()
        .ok()
}

fn depinfo_sentinel_for_source(source_sentinel: &str) -> Option<String> {
    if let Some(index) = configured_base_dir_index(source_sentinel) {
        return Some(format!("__kache_base_dir_{index}__/"));
    }
    Some(
        match source_sentinel {
            "<CWD>" => "__kache_cwd__/",
            "<WORKSPACE>" => "__kache_workspace__/",
            "<TARGET>" => "__kache_target_rule__/",
            "<CARGO_HOME>" => "__kache_cargo_home__/",
            "<BASE_DIR>" => "__kache_base_dir__/",
            "<RUSTUP_HOME>" => "__kache_rustup_home__/",
            "<HOME>" => "__kache_home__/",
            "<APPDATA>" => "__kache_appdata__/",
            "<LOCALAPPDATA>" => "__kache_localappdata__/",
            "<PROGRAMFILES>" => "__kache_programfiles__/",
            "<TMPDIR>" => "__kache_tmpdir__/",
            _ => return None,
        }
        .to_string(),
    )
}

/// The resolvable `--remap-path-prefix` target for a given cache-key sentinel.
///
/// All targets are ABSOLUTE (leading `/`) so DWARF consumers never compose a
/// relative `flag_target` onto `DW_AT_comp_dir` (the bug in #480, where
/// `<WORKSPACE>` + `<RUSTUP_HOME>` joined into
/// `<WORKSPACE>/<RUSTUP_HOME>/...`). `<WORKSPACE>` uses [`workspace_flag_target`]
/// so on Linux it becomes `/proc/self/cwd` (resolvable through the kernel when a
/// profiler runs from the workspace root); `<CARGO_HOME>` keeps the trailing
/// `/.cargo` so samply's crates.io matcher fires. `<RUST_SRC>` is handled
/// separately (its target carries the toolchain commit hash).
fn flag_target_for(key_sentinel: &str) -> String {
    match key_sentinel {
        "<WORKSPACE>" => workspace_flag_target().to_string(),
        "<BASE_DIR>" => "/kache/base-dir".to_string(),
        "<TARGET>" => "/kache/target".to_string(),
        "<CARGO_HOME>" => "/kache/.cargo".to_string(),
        "<RUSTUP_HOME>" => "/kache/rustup".to_string(),
        "<HOME>" => "/kache/home".to_string(),
        "<APPDATA>" => "/kache/appdata".to_string(),
        "<LOCALAPPDATA>" => "/kache/localappdata".to_string(),
        "<PROGRAMFILES>" => "/kache/programfiles".to_string(),
        "<TMPDIR>" => "/kache/tmp".to_string(),
        // Fall back to an absolute `/kache/<name>` token for any sentinel not
        // listed, so a future rule added without updating this map still yields
        // an absolute (non-composing) target rather than a relative `<FOO>`.
        other => format!(
            "/kache/{}",
            other.trim_matches(['<', '>']).to_ascii_lowercase()
        ),
    }
}

/// The `--remap-path-prefix` target for the workspace / build directory.
///
/// On Linux this is `/proc/self/cwd`, the Bazel trick: the kernel resolves it to
/// whatever the reading process's CWD is, so a profiler / debugger launched from
/// the workspace root opens workspace sources with no configuration, while the
/// baked bytes stay machine-independent (identical across checkouts → cache
/// hits transfer). Elsewhere (`/proc` absent) we use a fixed `/kache/workspace`
/// sentinel that debuggers can `substitute-path` / `source-map` back to the real
/// checkout. Per-OS divergence is safe: artifacts are already per-host (the full
/// `rustc -vV`, including `host:`, is hashed into the key).
fn workspace_flag_target() -> &'static str {
    if cfg!(target_os = "linux") {
        "/proc/self/cwd"
    } else {
        "/kache/workspace"
    }
}

/// Whether rustc path normalization is active. `KACHE_RUSTC_PATH_NORMALIZE`
/// set to `0` / `false` / `off` / `no` disables it; default on.
///
/// The analog of [`crate::compiler::cc`]'s `KACHE_CC_PATH_NORMALIZE`, but for
/// the rustc `--remap-path-prefix` injection. When disabled, kache injects no
/// remap flags — rustc bakes the real machine-local source paths into DWARF,
/// keeping debug info usable by local tooling (samply / Firefox Profiler,
/// `lldb`/`gdb` without `set substitute-path`). The trade-off mirrors the cc
/// toggle: rustc keys become non-portable across machines (they hash
/// `remap:none`, a distinct namespace from the default remapped builds), so
/// there is no cross-machine cache sharing for these artifacts — but zero
/// risk of a remapped binary being served where real paths were expected.
/// (The key also folds the raw local path identity in this case — see
/// `cache_key::fold_unremapped_path_identity` — so opt-out artifacts don't
/// leak across checkouts either.) Normalization stays ON by default: ordinary
/// builds remain portable (kunobi-ninja/kache#480).
pub fn rustc_path_normalize_enabled() -> bool {
    parse_rustc_normalize_toggle(std::env::var("KACHE_RUSTC_PATH_NORMALIZE").ok().as_deref())
}

/// Pure parse of the `KACHE_RUSTC_PATH_NORMALIZE` value (env read separately so
/// this stays unit-testable). Mirrors cc's `parse_cc_normalize_toggle`: only an
/// explicit falsey token disables normalization; unset / empty / unrecognized
/// keeps it on.
fn parse_rustc_normalize_toggle(value: Option<&str>) -> bool {
    match value {
        Some(v) => !matches!(
            v.trim().to_ascii_lowercase().as_str(),
            "0" | "false" | "off" | "no"
        ),
        None => true,
    }
}

/// Defense-in-depth: scan a string for substrings that look like
/// machine-local absolute paths and emit a warning naming the
/// context (which hash field, which value).
///
/// The relocate e2e phase already catches leaks by failing the build
/// when keys diverge across paths, but this gives a faster signal
/// during ad-hoc dev runs (a `KACHE_LOG=warn` user sees the leak the
/// first time they hit it instead of waiting for the full harness).
///
/// Only matches well-known absolute-path prefixes — avoids false
/// positives on legitimate strings that happen to contain `/`. The
/// list is intentionally conservative: missing a leak is preferable
/// to spamming the log on innocuous values.
///
/// `context` names where the value came from (e.g. `"normalize"`,
/// `"codegen:link-arg"`, `"cargo_cfg:MOZ_OBJ_DIR"`). It surfaces in the
/// warn so the offending field is identifiable without re-running with
/// trace-level logging.
pub(crate) fn check_for_path_leak(value: &str, context: &str) {
    const SUSPICIOUS_PREFIXES: &[&str] = &[
        "/Users/",       // macOS home
        "/home/",        // Linux home
        "/private/tmp/", // macOS canonicalized tempdir
        "/private/var/", // macOS canonicalized var
        "/var/folders/", // macOS per-user tempdir
        "C:\\Users\\",   // Windows home
    ];
    for prefix in SUSPICIOUS_PREFIXES {
        if let Some(idx) = value.find(prefix) {
            // Show a small window around the leak to make it easier
            // to identify (env var name etc.) without dumping the
            // whole value, which could be huge.
            let start = idx.saturating_sub(40);
            let end = (idx + prefix.len() + 40).min(value.len());
            tracing::warn!(
                "residual absolute path detected in `{}` (prefix `{}`): ...{}...",
                context,
                prefix,
                &value[start..end]
            );
            return;
        }
    }
}

/// Back-compat shim retained for `PathNormalizer::normalize` callers.
fn warn_if_path_leaked(s: &str) {
    check_for_path_leak(s, "PathNormalizer::normalize");
}

/// Canonicalize `path` to a string for prefix matching, or return
/// `None` if the path doesn't exist / can't be resolved. Empty
/// strings are also rejected because `String::replace("", x)` would
/// match between every byte and produce nonsense.
///
/// Returns the OS-native canonical form (Windows: `\` separators,
/// preserved case) **normalized to Unicode NFC**. The Windows
/// separator/case variants are added as ADDITIONAL rules by
/// [`push_rule_with_variants`] — keeping the OS-native form intact
/// lets `Path::starts_with` and other path-aware code consume this
/// string without surprise.
///
/// Why NFC: macOS filesystem APIs may return paths in NFD form
/// (HFS+ legacy, sometimes APFS); env vars typically use NFC. Both
/// rule and input get normalized to NFC at their respective sites
/// so byte-literal substring matching works regardless of which
/// form the source produced. See [`PathNormalizer::normalize`] for
/// the matching-side normalization.
pub(crate) fn canonical_string(path: &Path) -> Option<String> {
    let canon = path.canonicalize().ok()?;
    let lossy = canon.to_string_lossy();
    let s: String = strip_verbatim_prefix(&lossy).nfc().collect();
    if s.is_empty() { None } else { Some(s) }
}

/// Drop the Windows extended-length (`\\?\`) verbatim prefix that
/// [`Path::canonicalize`] returns on Windows.
///
/// Rule prefixes are matched against the paths cargo / rustc / env vars
/// actually emit, which are plain `C:\...` — never verbatim. Without
/// stripping, a rule like `\\?\C:\proj` can never substring-match an
/// input `C:\proj\...`, so on Windows *no* path normalization fired and
/// machine-local paths (notably `OUT_DIR`) leaked into the cache key,
/// breaking cross-path cache hits (kunobi-ninja/kache#201's relocate
/// miss). A `\\?\UNC\server\share` verbatim path is rewritten to its
/// `\\server\share` form. No-op on any string without the prefix
/// (always the case on Unix).
fn strip_verbatim_prefix(s: &str) -> std::borrow::Cow<'_, str> {
    if let Some(unc) = s.strip_prefix(r"\\?\UNC\") {
        std::borrow::Cow::Owned(format!(r"\\{unc}"))
    } else if let Some(drive) = s.strip_prefix(r"\\?\") {
        std::borrow::Cow::Borrowed(drive)
    } else {
        std::borrow::Cow::Borrowed(s)
    }
}

pub(crate) fn is_filesystem_root_prefix(value: &str) -> bool {
    let value = strip_verbatim_prefix(value);
    if value == "/" {
        return true;
    }
    let bytes = value.as_bytes();
    if bytes.len() == 3
        && bytes[0].is_ascii_alphabetic()
        && bytes[1] == b':'
        && matches!(bytes[2], b'/' | b'\\')
    {
        return true;
    }

    let normalized = value.replace('\\', "/");
    let Some(unc) = normalized.strip_prefix("//") else {
        return false;
    };
    let mut components = unc.trim_end_matches('/').split('/');
    components.next().is_some_and(|part| !part.is_empty())
        && components.next().is_some_and(|part| !part.is_empty())
        && components.next().is_none()
}

/// Push a rule + its Windows-shape variants into the rule list.
///
/// On unix, this is just `rules.push(Rule { prefix, sentinel })` —
/// one rule, no variants. On Windows the same canonical prefix
/// goes in *plus* up to three variants:
///
/// 1. **Forward-slash form** — cargo's dep-info often reports paths
///    with `/` even though the OS uses `\`. Without this variant
///    a stored `C:\Users\alice\.cargo` rule would miss an input
///    `C:/Users/alice/.cargo/registry/...`.
/// 2. **Lower-case drive letter** — NTFS is case-insensitive (`C:\`
///    and `c:\` are the same path) but `String::replace` is
///    byte-literal. Tools may emit either; both must match.
/// 3. **Both: lower-case drive + forward slash** — the cross of
///    the above when an input combines both deviations.
/// 4. **8.3 short-name form** — some tools emit a path's legacy short
///    name (`C:\PROGRA~1\...`) while the canonical rule is the long
///    form (`C:\Program Files\...`). The short form is resolved once
///    here via [`short_path_name`] and added (plus its own slash/case
///    crosses) so an 8.3 input still normalizes (issue #126).
///
/// Why this design over input transformation: an earlier draft
/// canonicalized the input string before matching. That worked for
/// cache-key hashing but had a side effect — parts of the input
/// that DIDN'T match a rule still got their separators flipped.
/// Storing variants instead means [`PathNormalizer::normalize`]
/// stays a dumb byte-literal substring replace; the input is treated
/// as opaque bytes outside any matched prefix. Duplicate variants
/// (e.g. a path with no 8.3 form) are pruned by the `dedup_by` in
/// [`PathNormalizer::from_env`].
fn push_rule_with_variants(rules: &mut Vec<Rule>, prefix: Option<String>, sentinel: &str) {
    // Derive the resolvable flag target from the sentinel. RUST_SRC (a dynamic
    // `/rustc/<hash>` target) goes through `push_rule_with_variants_target`.
    let flag_target = flag_target_for(sentinel);
    push_rule_with_variants_target(rules, prefix, sentinel, &flag_target);
}

fn push_rule_with_variants_source(
    rules: &mut Vec<Rule>,
    prefix: Option<String>,
    sentinel: &str,
    source_sentinel: &str,
) {
    let flag_target = flag_target_for(sentinel);
    push_rule_with_variants_target_and_source(
        rules,
        prefix,
        sentinel,
        source_sentinel,
        &flag_target,
    );
}

/// Add lexical and canonical spellings for one automatic source root.
///
/// Cargo can pass a lexical root while proc macros canonicalize included
/// files (`/var` versus `/private/var` on macOS, plain versus `\\?\` on
/// Windows). Every spelling maps to the same source identity/remap target and
/// is exposed through [`PathNormalizer::depinfo_source_roots`].
fn push_path_rule_aliases(
    rules: &mut Vec<Rule>,
    source_restore_roots: &mut Vec<(String, PathBuf)>,
    path: &Path,
    sentinel: &str,
    source_sentinel: &str,
) {
    let lexical = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
    source_restore_roots.push((source_sentinel.to_string(), lexical.clone()));
    let mut spellings = os_path_spellings(&lexical);
    if let Ok(canonical) = path.canonicalize()
        && canonical != lexical
    {
        spellings.extend(os_path_spellings(&canonical));
    }
    spellings.sort_by_key(|prefix| std::cmp::Reverse(prefix.len()));
    spellings.dedup();
    for prefix in spellings {
        push_rule_with_variants_source(rules, Some(prefix), sentinel, source_sentinel);
    }
}

/// Add the legacy explicit source root without letting an empty value or a
/// filesystem root erase every absolute-path distinction.
fn push_legacy_base_dir_rules(
    rules: &mut Vec<Rule>,
    source_restore_roots: &mut Vec<(String, PathBuf)>,
    base_dir: Option<&std::ffi::OsStr>,
) {
    let Some(base_dir) = base_dir.filter(|value| !value.is_empty()) else {
        return;
    };
    let path = Path::new(base_dir);
    let absolute = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
    let Some(prefix) = absolute.as_os_str().to_str() else {
        return;
    };
    if is_filesystem_root_prefix(prefix) {
        return;
    }
    push_path_rule_aliases(
        rules,
        source_restore_roots,
        path,
        "<BASE_DIR>",
        "<BASE_DIR>",
    );
}

/// Preserve raw filesystem spelling while also adding the NFC/key form and
/// the ordinary Windows spelling of a verbatim canonical path.
fn os_path_spellings(path: &Path) -> Vec<String> {
    let Some(raw) = path.as_os_str().to_str().filter(|value| !value.is_empty()) else {
        return Vec::new();
    };
    let normalized: String = raw.nfc().collect();
    let stripped = strip_verbatim_prefix(&normalized).into_owned();
    let mut spellings = vec![raw.to_string(), normalized, stripped];
    spellings.retain(|spelling| !is_filesystem_root_prefix(spelling));
    spellings.dedup();
    spellings
}

/// As [`push_rule_with_variants`] but with an explicit `flag_target`, for rules
/// whose target isn't derivable from the sentinel alone (e.g. `<RUST_SRC>` →
/// `/rustc/<commit-hash>`).
fn push_rule_with_variants_target(
    rules: &mut Vec<Rule>,
    prefix: Option<String>,
    sentinel: &str,
    flag_target: &str,
) {
    push_rule_with_variants_target_and_source(rules, prefix, sentinel, sentinel, flag_target);
}

fn push_rule_with_variants_target_and_source(
    rules: &mut Vec<Rule>,
    prefix: Option<String>,
    sentinel: &str,
    source_sentinel: &str,
    flag_target: &str,
) {
    let Some(prefix) = prefix else { return };
    if prefix.is_empty() {
        return;
    }

    // Always push the canonical form first.
    rules.push(Rule {
        prefix: prefix.clone(),
        key_sentinel: sentinel.to_string(),
        source_sentinel: source_sentinel.to_string(),
        flag_target: flag_target.to_string(),
    });

    // Variants only matter on Windows. On unix the canonical form
    // is the only one cargo / rustc / env vars produce, so adding
    // variants would just be dead rules.
    if !cfg!(windows) {
        return;
    }

    push_slash_and_case_variants(rules, &prefix, sentinel, source_sentinel, flag_target);

    // 8.3 short-name form (issue #126). Resolved once at rule-build
    // time; `None` when the path doesn't exist, has no short name, or
    // 8.3 generation is disabled on the volume — in which case there's
    // nothing to add. The short form gets the same slash/case crosses.
    if let Some(short) = short_path_name(&prefix)
        && short != prefix
    {
        rules.push(Rule {
            prefix: short.clone(),
            key_sentinel: sentinel.to_string(),
            source_sentinel: source_sentinel.to_string(),
            flag_target: flag_target.to_string(),
        });
        push_slash_and_case_variants(rules, &short, sentinel, source_sentinel, flag_target);
    }
}

/// Push the forward-slash, lower-case-drive, and combined variants of a
/// single Windows prefix. The canonical form is expected to have been
/// pushed already by the caller. Each variant is only added when it
/// actually differs from the forms already covered.
fn push_slash_and_case_variants(
    rules: &mut Vec<Rule>,
    prefix: &str,
    sentinel: &str,
    source_sentinel: &str,
    flag_target: &str,
) {
    let push = |rules: &mut Vec<Rule>, p: String| {
        rules.push(Rule {
            prefix: p,
            key_sentinel: sentinel.to_string(),
            source_sentinel: source_sentinel.to_string(),
            flag_target: flag_target.to_string(),
        });
    };

    // Forward-slash variant.
    let fs = prefix.replace('\\', "/");
    if fs != prefix {
        push(rules, fs.clone());
    }

    // Backslash variant — when the canonical arrives in forward-slash form
    // (e.g. a `CARGO_HOME` set with `/`), rustc/cargo still emit `\` paths, so
    // the backslash form must be in the rule set too. The `replace('\\', "/")`
    // above only covers the opposite direction.
    let bs = prefix.replace('/', "\\");
    if bs != prefix {
        push(rules, bs.clone());
    }

    // Lower-case drive variant.
    let lc = lowercase_drive_letter(prefix);
    if let Some(ref lc_str) = lc
        && lc_str != prefix
    {
        push(rules, lc_str.clone());
    }

    // Both: forward-slash + lower-case drive.
    if let Some(fs_lc) = lowercase_drive_letter(&fs)
        && fs_lc != fs
        && Some(&fs_lc) != lc.as_ref()
    {
        push(rules, fs_lc);
    }

    // Both: backslash + lower-case drive.
    if let Some(bs_lc) = lowercase_drive_letter(&bs)
        && bs_lc != bs
        && Some(&bs_lc) != lc.as_ref()
    {
        push(rules, bs_lc);
    }
}

/// Resolve a path's Windows 8.3 short name (e.g. `C:\Program Files` →
/// `C:\PROGRA~1`) via `GetShortPathNameW`. Returns `None` when the path
/// doesn't exist, the volume has 8.3 generation disabled, or the call
/// otherwise fails — all of which simply mean "no short-name variant to
/// add". Off Windows this is always `None`.
#[cfg(windows)]
fn short_path_name(path: &str) -> Option<String> {
    use std::ffi::{OsStr, OsString};
    use std::os::windows::ffi::{OsStrExt, OsStringExt};
    use windows_sys::Win32::Storage::FileSystem::GetShortPathNameW;

    let wide: Vec<u16> = OsStr::new(path)
        .encode_wide()
        .chain(std::iter::once(0))
        .collect();

    // First call with a zero-length buffer returns the required length
    // INCLUDING the terminating NUL (0 on error).
    let needed = unsafe { GetShortPathNameW(wide.as_ptr(), std::ptr::null_mut(), 0) };
    if needed == 0 {
        return None;
    }

    let mut buf = vec![0u16; needed as usize];
    // On success the buffer is large enough, so this returns the length
    // EXCLUDING the NUL (i.e. < needed). 0 = error; >= needed = a race
    // where the path grew between calls — treat both as "no variant".
    let written = unsafe { GetShortPathNameW(wide.as_ptr(), buf.as_mut_ptr(), needed) };
    if written == 0 || written >= needed {
        return None;
    }

    Some(
        OsString::from_wide(&buf[..written as usize])
            .to_string_lossy()
            .into_owned(),
    )
}

#[cfg(not(windows))]
fn short_path_name(_path: &str) -> Option<String> {
    None
}

/// Return `Some(s with first byte lowercased)` if `s` looks like
/// a Windows drive-letter path (`X:` prefix where X is an ASCII
/// uppercase letter), else `None`. Only the drive letter is touched —
/// rest of the path is preserved (Windows filesystems are typically
/// case-preserving even when case-insensitive).
///
/// Operates at the BYTE level, not the `&str` slice level, to stay
/// panic-safe on inputs that start with a multi-byte UTF-8 codepoint.
/// `&s[1..2]` would panic with "not a char boundary" when byte 0 is
/// the start of (e.g.) `É` (`0xC3 0x89` in UTF-8). Drive letters are
/// always ASCII A-Z in practice, but defensive — `Path::canonicalize`
/// can return paths starting with anything when working with weird
/// volume labels or junctions.
fn lowercase_drive_letter(s: &str) -> Option<String> {
    let bytes = s.as_bytes();
    if bytes.len() < 2 || bytes[1] != b':' || !bytes[0].is_ascii_uppercase() {
        return None;
    }
    let mut out = s.to_string();
    // SAFETY: replacing one ASCII byte with another ASCII byte
    // preserves UTF-8 validity. Byte 0 was confirmed ASCII above.
    unsafe {
        out.as_bytes_mut()[0] = bytes[0].to_ascii_lowercase();
    }
    Some(out)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fs;
    use tempfile::TempDir;

    /// The `KACHE_RUSTC_PATH_NORMALIZE` opt-out mirrors the cc toggle
    /// (`KACHE_CC_PATH_NORMALIZE`): normalization is the default, and only an
    /// explicit `0`/`false`/`off`/`no` (case- and whitespace-insensitive)
    /// disables it. Anything else — including unset, empty, or garbage — keeps
    /// it on. This is what lets a local samply/Firefox-Profiler user turn off
    /// rustc `--remap-path-prefix` injection so debug info keeps real source
    /// paths (kunobi-ninja/kache#480).
    #[test]
    fn parse_rustc_normalize_toggle_defaults_on_opts_out_explicitly() {
        for on in [
            None,
            Some("1"),
            Some("yes"),
            Some("on"),
            Some(""),
            Some("garbage"),
        ] {
            assert!(parse_rustc_normalize_toggle(on), "{on:?} should keep it on");
        }
        for off in [
            Some("0"),
            Some("false"),
            Some("off"),
            Some("no"),
            Some("  OFF "),
        ] {
            assert!(
                !parse_rustc_normalize_toggle(off),
                "{off:?} should disable it"
            );
        }
    }

    #[test]
    fn empty_normalizer_is_identity() {
        let n = PathNormalizer::empty();
        assert_eq!(n.normalize("/anything/at/all"), "/anything/at/all");
        assert_eq!(n.normalize(""), "");
    }

    #[test]
    fn canonicalizes_workspace_prefix_and_replaces_with_sentinel() {
        // Real on-disk dir so `canonicalize` succeeds.
        let dir = TempDir::new().unwrap();
        let n = PathNormalizer::from_env(Some(dir.path()));
        let canonical = dir.path().canonicalize().unwrap();
        let input = format!("{}/src/main.rs", canonical.display());
        assert!(
            n.normalize(&input).contains("<WORKSPACE>"),
            "got {} for input {input}",
            n.normalize(&input)
        );
    }

    #[test]
    fn workspace_rule_strips_macos_private_tmp_symlink() {
        // The exact bug class this struct exists to prevent: macOS
        // `/tmp` → `/private/tmp` symlink. A literal-replace
        // implementation that didn't canonicalize would miss when
        // the env var contains the canonicalized form but CWD
        // reports the symlink form (or vice versa).
        if !cfg!(target_os = "macos") {
            return;
        }
        // Construct a real dir under /tmp (the symlink form). The
        // normalizer canonicalizes to /private/tmp internally, so an
        // OUT_DIR-style string using the canonical form should match.
        let symlink_root = Path::new("/tmp");
        let unique = format!("kache-pn-test-{}", std::process::id());
        let real_dir = symlink_root.join(&unique);
        let _ = fs::create_dir_all(&real_dir);
        let n = PathNormalizer::from_env(Some(&real_dir));
        let private_form = format!("/private/tmp/{unique}/target/release/build/foo/out");
        let normalized = n.normalize(&private_form);
        let _ = fs::remove_dir_all(&real_dir);
        assert!(
            normalized.starts_with("<WORKSPACE>"),
            "expected <WORKSPACE> sentinel, got {normalized:?}"
        );
    }

    #[test]
    fn home_rule_normalizes_paths_inside_home() {
        let n = PathNormalizer::from_env(None);
        if let Some(home) = dirs::home_dir().and_then(|p| p.canonicalize().ok()) {
            // Windows `canonicalize()` yields a `\\?\C:\…` verbatim path; real
            // cargo/rustc paths don't carry that prefix, so strip it before
            // building the test input (no-op on Unix).
            let home = home.display().to_string();
            let home = home.strip_prefix(r"\\?\").unwrap_or(&home);
            let input = format!("{home}/some/thing");
            // Either <HOME> or <CARGO_HOME> may match (cargo home is
            // inside home by default). Either is a valid normalization.
            let out = n.normalize(&input);
            assert!(
                out.starts_with('<'),
                "expected a sentinel prefix, got {out:?}"
            );
        }
    }

    #[test]
    fn empty_prefix_does_not_corrupt_input() {
        // Defense-in-depth: an empty prefix would make
        // `String::replace("", x)` match at every byte boundary,
        // producing garbage. The constructor rejects empty prefixes,
        // and `normalize` skips them as belt-and-braces.
        let n = PathNormalizer {
            rules: vec![Rule {
                prefix: String::new(),
                key_sentinel: "<NEVER>".to_string(),
                source_sentinel: "<NEVER>".to_string(),
                flag_target: "<NEVER>".to_string(),
            }],
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };
        assert_eq!(n.normalize("hello world"), "hello world");
    }

    #[test]
    fn unmatched_input_passes_through_unchanged() {
        let n = PathNormalizer::from_env(None);
        let input = "this/path/does/not/match/anything/local";
        assert_eq!(n.normalize(input), input);
    }

    #[test]
    fn from_env_includes_rustup_home_rule_when_dir_exists() {
        // Default RUSTUP_HOME is `~/.rustup`; the dir typically exists
        // in any test environment with rustup installed (which is the
        // common case for kache contributors). Skip the assertion if
        // the dir really doesn't exist — better to skip than spam CI
        // with environment-dependent flakes.
        let rustup_dir = dirs::home_dir().map(|h| h.join(".rustup"));
        let Some(dir) = rustup_dir else {
            return;
        };
        if !dir.exists() {
            return;
        }
        let n = PathNormalizer::from_env(None);
        let canonical = dir.canonicalize().unwrap();
        let input = format!("{}/toolchains/stable/bin/rustc", canonical.display());
        let out = n.normalize(&input);
        assert!(
            out.contains("<RUSTUP_HOME>") || out.contains("<HOME>"),
            "expected rustup or home sentinel in {out:?}"
        );
    }

    #[test]
    fn from_env_includes_tempdir_rule() {
        let n = PathNormalizer::from_env(None);
        let temp = std::env::temp_dir().canonicalize().unwrap();
        let input = format!("{}/some-build-artifact", temp.display());
        let out = n.normalize(&input);
        // On macOS the tempdir is `/var/folders/.../T` which is also
        // inside the canonical /private/var path; either sentinel is
        // a valid normalization.
        assert!(
            out.contains("<TMPDIR>") || out.contains("<HOME>") || out.starts_with('<'),
            "expected a sentinel for tempdir-based path, got {out:?}"
        );
    }

    #[test]
    fn from_env_includes_cwd_rule_for_comp_dir() {
        // The CWD rule is what rewrites rustc's DWARF `DW_AT_comp_dir`:
        // rustc records its working directory there verbatim, and the
        // other rules only rewrite it if one's prefix matches the CWD
        // exactly. Without this rule a debug build leaks the build path
        // through `comp_dir`. kache runs as RUSTC_WRAPPER with no
        // `chdir`, so the wrapper CWD is the CWD rustc records.
        let cwd = std::env::current_dir().unwrap();
        let canonical = canonical_string(&cwd).expect("cwd must canonicalize");
        let n = PathNormalizer::from_env(None);

        // The CWD must normalize to a sentinel (`<WORKSPACE>` — possibly
        // shadowed by an inner rule, hence the looser `starts_with`).
        let normalized = n.normalize(format!("{canonical}/src/main.rs"));
        assert!(
            normalized.starts_with('<'),
            "CWD path should normalize to a sentinel, got {normalized:?}"
        );

        // ...and the rule must surface as an injected `--remap-path-prefix`
        // whose TARGET is the resolvable workspace spelling (`/proc/self/cwd`
        // on Linux, `/kache/workspace` elsewhere) — no longer the relative
        // `<WORKSPACE>` sentinel, which would compose onto comp_dir (#480).
        let remaps = n.remap_args();
        let expected = format!(
            "--remap-path-prefix={canonical}={}",
            workspace_flag_target()
        );
        assert!(
            remaps.iter().any(|a| a == &expected),
            "from_env must emit a CWD remap arg mapping to the resolvable \
             workspace target; wanted {expected:?}, got {remaps:?}"
        );
    }

    #[test]
    fn remap_args_targets_are_absolute_and_carry_no_sentinel() {
        // Every injected target must be an ABSOLUTE path (leading `/`) and must
        // NOT be an angle-bracket sentinel. Absolute targets are what stop a
        // DWARF consumer composing a relative target onto `DW_AT_comp_dir` into
        // garbage like `<WORKSPACE>/<RUSTUP_HOME>/...` (#480).
        let dir = TempDir::new().unwrap();
        let n = PathNormalizer::from_env(Some(dir.path()));
        let args = n.remap_args();
        assert!(!args.is_empty());
        for arg in &args {
            let body = arg
                .strip_prefix("--remap-path-prefix=")
                .expect("rustc-recognized shape");
            let (_, target) = body.rsplit_once('=').expect("PREFIX=TARGET shape");
            assert!(
                target.starts_with('/'),
                "target must be absolute, got {target:?}"
            );
            assert!(
                !target.contains('<') && !target.contains('>'),
                "target must not be an angle-bracket sentinel, got {target:?}"
            );
        }
    }

    #[test]
    fn remap_args_orders_cargo_home_and_rustup_after_workspace() {
        // Load-bearing precedence for #485: because rustc applies
        // `--remap-path-prefix` with last-match-wins (single winning mapping,
        // suffix preserved), `<CARGO_HOME>` and `<RUST_SRC>` must be emitted
        // AFTER `<WORKSPACE>`. That way a crates.io dep — whose CWD is INSIDE
        // `$CARGO_HOME`, so its comp_dir matches both rules — resolves under
        // `/kache/.cargo` (samply → crates.io), while a workspace member (not
        // under `$CARGO_HOME`) keeps `/proc/self/cwd`. `<HOME>` must precede
        // `<WORKSPACE>` for the same reason (a workspace inside `$HOME`).
        let dir = TempDir::new().unwrap();
        let n = PathNormalizer::from_env(Some(dir.path()))
            .with_rust_src_rule(Some(Path::new("/nonexistent/sysroot")), Some("deadbeef"));
        let args = n.remap_args();

        let pos = |needle: &str| args.iter().position(|a| a.ends_with(needle));
        let ws = pos(&format!("={}", workspace_flag_target()));
        let home = pos("=/kache/home");
        let cargo = pos("=/kache/.cargo");
        // rank ordering is unconditional, so wherever a rule exists its relative
        // order must hold. (rust-src rule is dropped here — sysroot is fake — so
        // we don't assert on it; the rank fn is unit-tested separately.)
        if let (Some(h), Some(w)) = (home, ws) {
            assert!(h < w, "HOME must precede WORKSPACE; got {args:#?}");
        }
        if let (Some(w), Some(c)) = (ws, cargo) {
            assert!(w < c, "WORKSPACE must precede CARGO_HOME; got {args:#?}");
        }
    }

    #[test]
    fn flag_emit_rank_encodes_the_load_bearing_precedence() {
        // RUST_SRC and CARGO_HOME outrank WORKSPACE (dep/std sources win over
        // the cwd rule they nest inside); TARGET and the user dirs rank below.
        assert!(flag_emit_rank("<RUST_SRC>") > flag_emit_rank("<CARGO_HOME>"));
        assert!(flag_emit_rank("<CARGO_HOME>") > flag_emit_rank("<WORKSPACE>"));
        assert!(flag_emit_rank("<WORKSPACE>") > flag_emit_rank("<TARGET>"));
        assert!(flag_emit_rank("<RUSTUP_HOME>") > flag_emit_rank("<HOME>"));
        assert!(flag_emit_rank("<RUST_SRC>") > flag_emit_rank("<RUSTUP_HOME>"));
        assert!(flag_emit_rank("<HOME>") > flag_emit_rank("<TMPDIR>"));
    }

    #[test]
    fn workspace_flag_target_is_pinned_per_os() {
        // Pin the literal per-OS value (other tests call the function itself and
        // would pass even if it returned a wrong-but-absolute string).
        let t = workspace_flag_target();
        assert!(t.starts_with('/'));
        #[cfg(target_os = "linux")]
        assert_eq!(t, "/proc/self/cwd");
        #[cfg(not(target_os = "linux"))]
        assert_eq!(t, "/kache/workspace");
    }

    #[test]
    fn flag_target_for_maps_known_sentinels_to_absolute_resolvable_paths() {
        assert_eq!(flag_target_for("<CARGO_HOME>"), "/kache/.cargo");
        assert!(
            flag_target_for("<CARGO_HOME>").ends_with("/.cargo"),
            "CARGO_HOME target must keep the /.cargo tail for samply's crates.io matcher"
        );
        assert_eq!(flag_target_for("<WORKSPACE>"), workspace_flag_target());
        // Unlisted sentinel falls back to an absolute /kache/<name> token.
        assert_eq!(flag_target_for("<FUTURE_THING>"), "/kache/future_thing");
    }

    #[test]
    fn remap_args_skips_empty_prefixes() {
        // Defense-in-depth: an empty prefix would emit
        // `--remap-path-prefix==<SENTINEL>`, which rustc would
        // probably accept and apply to every path (corrupting
        // every embedded path string). Mirror the same skip the
        // `normalize` method does.
        let n = PathNormalizer {
            rules: vec![Rule {
                prefix: String::new(),
                key_sentinel: "<NEVER>".to_string(),
                source_sentinel: "<NEVER>".to_string(),
                flag_target: "<NEVER>".to_string(),
            }],
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };
        assert!(n.remap_args().is_empty());
    }

    // ── Windows-shape variants ──────────────────────────────────
    //
    // These tests exercise the "store multiple variants per rule"
    // strategy that handles Windows separator + drive-case
    // differences without transforming the input string. Each test
    // can run on any host; the cfg!(windows) gates select the
    // expected behavior (variants are added on Windows, skipped
    // elsewhere).

    fn rules_for(n: &PathNormalizer) -> Vec<(String, String)> {
        n.rules
            .iter()
            .map(|r| (r.prefix.clone(), r.key_sentinel.clone()))
            .collect()
    }

    #[test]
    fn lowercase_drive_letter_only_touches_first_byte() {
        // Drive letter lowercased; rest of path preserved exactly
        // (Windows is case-preserving even when case-insensitive).
        assert_eq!(
            lowercase_drive_letter("C:\\Users\\Alice"),
            Some("c:\\Users\\Alice".to_string())
        );
        assert_eq!(
            lowercase_drive_letter("D:/Projects/Foo"),
            Some("d:/Projects/Foo".to_string())
        );
    }

    #[test]
    fn lowercase_drive_letter_returns_none_for_non_drive_paths() {
        // Unix paths, already-lowercase drives, and short strings
        // all return None — caller treats that as "no variant".
        assert_eq!(lowercase_drive_letter("/unix/path"), None);
        assert_eq!(lowercase_drive_letter("c:\\already\\lower"), None);
        assert_eq!(lowercase_drive_letter("C"), None);
        assert_eq!(lowercase_drive_letter(""), None);
        assert_eq!(lowercase_drive_letter("CD"), None); // missing :
        assert_eq!(lowercase_drive_letter("1:\\foo"), None); // not a letter
    }

    #[test]
    fn push_rule_with_variants_adds_only_canonical_form_on_unix() {
        // On unix the canonical form is the only one cargo / rustc
        // produce, so variants would be dead rules. This test pins
        // that contract (would fail loudly if someone changed the
        // gate to add variants unconditionally — wasted memory and
        // a tiny risk of unexpected matches).
        if cfg!(windows) {
            return;
        }
        let mut rules = Vec::new();
        push_rule_with_variants(
            &mut rules,
            Some("/Users/alice/.cargo".to_string()),
            "<CARGO_HOME>",
        );
        assert_eq!(rules.len(), 1);
        assert_eq!(rules[0].prefix, "/Users/alice/.cargo");
        assert_eq!(rules[0].key_sentinel, "<CARGO_HOME>");
    }

    #[test]
    fn push_rule_with_variants_expands_on_windows() {
        // The contract: a single Windows-shaped prefix expands to
        // up to four variants — canonical, forward-slash,
        // lowercase-drive, and both. Each variant maps to the
        // SAME sentinel so any of the input forms gets normalized.
        if !cfg!(windows) {
            return;
        }
        let mut rules = Vec::new();
        push_rule_with_variants(
            &mut rules,
            Some("C:\\Users\\Alice\\.cargo".to_string()),
            "<CARGO_HOME>",
        );
        // All variants present, all map to <CARGO_HOME>.
        let prefixes: Vec<&str> = rules.iter().map(|r| r.prefix.as_str()).collect();
        assert!(prefixes.contains(&"C:\\Users\\Alice\\.cargo"));
        assert!(prefixes.contains(&"C:/Users/Alice/.cargo"));
        assert!(prefixes.contains(&"c:\\Users\\Alice\\.cargo"));
        assert!(prefixes.contains(&"c:/Users/Alice/.cargo"));
        assert!(rules.iter().all(|r| r.key_sentinel == "<CARGO_HOME>"));
    }

    /// Issue #126: a path's legacy 8.3 short name (`...\LONGPR~1`) must
    /// normalize to the same sentinel as its long form. Windows-only and
    /// dependent on the volume having 8.3 generation enabled, so it
    /// resolves the real short name for an existing dir and skips if the
    /// volume has short names disabled (rather than flaking).
    #[cfg(windows)]
    #[test]
    fn push_rule_with_variants_adds_8dot3_short_name() {
        // A name with a space and >8 chars forces an 8.3 alias when the
        // volume supports it (e.g. "Long Program Dir" -> "LONGPR~1").
        let tmp = TempDir::new().unwrap();
        let long_dir = tmp.path().join("Long Program Dir");
        fs::create_dir(&long_dir).unwrap();
        let canonical = canonical_string(&long_dir).expect("canonicalize long dir");

        // No short name (8.3 disabled on this volume) -> nothing to test.
        let Some(short) = short_path_name(&canonical) else {
            return;
        };
        if short == canonical {
            return;
        }

        let mut rules = Vec::new();
        push_rule_with_variants(&mut rules, Some(canonical), "<BASE_DIR>");
        let n = PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };

        let input = format!("{short}\\src\\main.rs");
        let out = n.normalize(&input);
        assert!(
            out.contains("<BASE_DIR>"),
            "8.3 short-name input {input:?} should normalize via the short variant, got {out:?}"
        );
        assert_eq!(
            n.source_path_identity(Path::new(&input)).unwrap(),
            b"<BASE_DIR>/src\\main.rs"
        );
        assert!(
            n.depinfo_source_roots()
                .iter()
                .any(|root| root.root.as_path() == Path::new(short.as_str())),
            "the same short spelling must be accepted while relativizing dep-info"
        );
    }

    #[test]
    fn push_rule_with_variants_skips_empty_and_none() {
        // Defense-in-depth: an empty prefix would corrupt every
        // input via `String::replace("", x)`. None means "this
        // rule's source isn't available" (env var unset, dir
        // doesn't exist) and should be silently skipped.
        let mut rules = Vec::new();
        push_rule_with_variants(&mut rules, None, "<NEVER>");
        push_rule_with_variants(&mut rules, Some(String::new()), "<NEVER>");
        assert!(rules.is_empty());
    }

    #[test]
    fn normalize_matches_any_variant_form() {
        // The motivating Windows case: a stored canonical prefix
        // plus inputs that may use any of the four variants. All
        // should normalize to the same sentinel because we stored
        // every variant at construction.
        let mut rules = Vec::new();
        push_rule_with_variants(
            &mut rules,
            Some("C:\\Users\\Alice\\.cargo".to_string()),
            "<CARGO_HOME>",
        );
        let n = PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };

        // On unix only the canonical form is in the rule set, so
        // only that input is matched; on Windows any of the four
        // forms should match.
        let inputs_and_expectations: &[(&str, bool)] = &[
            ("C:\\Users\\Alice\\.cargo\\registry\\foo", true), // canonical
            ("C:/Users/Alice/.cargo/registry/foo", cfg!(windows)),
            ("c:\\Users\\Alice\\.cargo\\registry\\foo", cfg!(windows)),
            ("c:/Users/Alice/.cargo/registry/foo", cfg!(windows)),
            ("/Users/alice/.cargo/registry/foo", false), // unix path, never matches
        ];
        for (input, should_match) in inputs_and_expectations {
            let out = n.normalize(input);
            let matched = out.contains("<CARGO_HOME>");
            assert_eq!(
                matched, *should_match,
                "input {input:?}: expected match={should_match}, got out={out:?}"
            );
        }
    }

    #[test]
    fn normalize_does_not_transform_unmatched_input() {
        // Critical contract: input bytes that DON'T match any rule
        // must come out byte-identical. The earlier
        // canonicalize-input design failed this — it flipped
        // backslashes everywhere. The current variant-based design
        // never transforms; this test pins that.
        let n = PathNormalizer::empty();
        let weird_inputs = &[
            "C:\\Users\\foo",
            "/unix/with\\backslash/mixed",
            r"\\?\C:\extended\length",
            "\\//\\/", // mixed-up separators (the user's concern)
            "no path here at all",
        ];
        for input in weird_inputs {
            assert_eq!(
                n.normalize(input),
                *input,
                "unmatched input {input:?} must pass through unchanged"
            );
        }
    }

    #[test]
    fn rules_dedup_keeps_first_for_identical_canonicalization() {
        // On unix, when the canonical forms of two different sources
        // (e.g. CARGO_HOME and HOME if CARGO_HOME = HOME, weird but
        // possible in tests) collide, the first-listed sentinel
        // wins. push_rule_with_variants pushes the canonical first
        // for each, so dedup_by removes only the duplicate.
        let mut rules = Vec::new();
        push_rule_with_variants(&mut rules, Some("/same/path".to_string()), "<FIRST>");
        push_rule_with_variants(&mut rules, Some("/same/path".to_string()), "<SECOND>");
        // Mirror the real `from_env` global keep-first dedup.
        let mut seen = std::collections::HashSet::new();
        rules.retain(|r| seen.insert(r.prefix.clone()));
        let names: Vec<_> = rules_for(&PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        })
        .into_iter()
        .collect();
        // The SECOND source's prefixes all duplicate the FIRST's, so every
        // surviving rule comes from FIRST. (Unix: one rule for `/same/path`;
        // Windows: that plus the backslash variant — all `<FIRST>`.)
        assert!(!names.is_empty());
        assert!(names.iter().all(|(_, sentinel)| *sentinel == "<FIRST>"));
        assert!(names.iter().any(|(prefix, _)| prefix == "/same/path"));
        // No prefix survives more than once.
        let unique: std::collections::HashSet<_> = names.iter().map(|(p, _)| p).collect();
        assert_eq!(unique.len(), names.len());
    }

    #[test]
    fn leak_detector_does_not_panic_on_unsentineled_paths() {
        // The detector logs but doesn't error — failure mode is
        // observability, not correctness. This test pins that
        // behavior so a future change doesn't accidentally make
        // leak detection panic.
        let n = PathNormalizer::empty();
        // Empty normalizer leaves input untouched; if the input
        // contains a suspicious path, the detector logs.
        let _ = n.normalize("/Users/alice/leaked/path");
        let _ = n.normalize("/home/bob/leaked/path");
        let _ = n.normalize("C:\\Users\\charlie\\leaked");
        // No assertions on log output (we don't capture tracing in
        // unit tests); the assertion is "did not panic".
    }

    // ── Extended edge-case coverage ─────────────────────────────
    //
    // The tests above cover the basic surface (empty/non-empty
    // normalizers, sentinel substitution, Windows variants). This
    // section exercises edge cases that aren't immediately obvious
    // from the basic tests but matter for real-world inputs:
    //
    //   - Multiple occurrences of the same prefix in one input
    //   - The boundary case where the input EQUALS the prefix
    //   - Multiple distinct prefixes chained in one input
    //   - Nested prefixes (workspace inside home; most-specific wins)
    //   - Idempotency (sentinels themselves don't get re-replaced)
    //   - The known limitation: substring vs. path-component matching
    //   - Realistic OUT_DIR / RUSTFLAGS-shape inputs end-to-end

    fn pn_with_rules(rules: Vec<(&str, &'static str)>) -> PathNormalizer {
        // Test helper: build a normalizer with explicit rules,
        // bypassing the env-derived `from_env` so tests are
        // deterministic across hosts.
        PathNormalizer {
            rules: rules
                .into_iter()
                .map(|(p, s)| Rule {
                    prefix: p.to_string(),
                    key_sentinel: s.to_string(),
                    source_sentinel: s.to_string(),
                    flag_target: flag_target_for(s),
                })
                .collect(),
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        }
    }

    /// Simulate rustc's `--remap-path-prefix` resolution of `path`: among all
    /// FROM prefixes that match, the LAST-emitted mapping wins; its prefix is
    /// replaced and the suffix preserved (mappings are not chained). This
    /// mirrors rustc's `FilePathMapping` last-match-wins and lets us assert the
    /// exact DWARF spelling a build would bake in.
    fn apply_last_match(args: &[String], path: &str) -> String {
        let mut winner: Option<(String, String)> = None;
        for a in args {
            let body = a.strip_prefix("--remap-path-prefix=").unwrap();
            let (from, to) = body.rsplit_once('=').unwrap();
            if path.starts_with(from) {
                winner = Some((from.to_string(), to.to_string()));
            }
        }
        match winner {
            Some((from, to)) => format!("{to}{}", &path[from.len()..]),
            None => path.to_string(),
        }
    }

    #[test]
    fn registry_dep_comp_dir_maps_under_cargo_home_via_last_match() {
        // The #485 crux, end to end. cargo compiles a crates.io dep with CWD
        // inside `$CARGO_HOME`, so both the cwd rule and the CARGO_HOME rule
        // match the dep's `comp_dir`. rustc's last-match-wins + our rank order
        // must yield a `/kache/.cargo/...` comp_dir (samply resolves it to
        // crates.io) rather than `/proc/self/cwd`.
        let cargo_home = "/home/u/.cargo";
        let dep_dir = "/home/u/.cargo/registry/src/index.crates.io-abc/itoa-1.0.18";
        let n = pn_with_rules(vec![
            (dep_dir, "<WORKSPACE>"), // cwd rule as set for a registry dep
            (cargo_home, "<CARGO_HOME>"),
        ]);
        assert_eq!(
            apply_last_match(&n.remap_args(), dep_dir),
            "/kache/.cargo/registry/src/index.crates.io-abc/itoa-1.0.18",
            "a registry dep's comp_dir must resolve under /kache/.cargo"
        );

        // A workspace member (NOT under $CARGO_HOME) keeps the workspace target.
        let member = "/repo/crates/foo";
        let n2 = pn_with_rules(vec![(member, "<WORKSPACE>"), (cargo_home, "<CARGO_HOME>")]);
        assert_eq!(
            apply_last_match(&n2.remap_args(), member),
            workspace_flag_target(),
            "a workspace member must keep the workspace target"
        );
    }

    #[test]
    fn workspace_member_maps_via_cwd_not_repo_root() {
        // Regression (codex cross-family review): the cwd rule and the shallower
        // workspace-root rule share rank 4. rustc's last-match-wins means the
        // rule emitted LAST wins, so the LONGER (cwd) prefix must be emitted last
        // — otherwise a member at /repo/crates/foo maps its sources via /repo to
        // /proc/self/cwd/crates/foo/..., which resolves (through the cwd symlink)
        // to /repo/crates/foo/crates/foo/... — a doubled, non-existent path.
        let member = "/repo/crates/foo";
        let repo = "/repo";
        // Insertion order mirrors from_env: cwd first, then workspace_root.
        let n = pn_with_rules(vec![(member, "<WORKSPACE>"), (repo, "<WORKSPACE>")]);
        assert_eq!(
            apply_last_match(&n.remap_args(), &format!("{member}/src/lib.rs")),
            format!("{}/src/lib.rs", workspace_flag_target()),
            "a workspace member's own source must map via the cwd prefix, not the repo root"
        );
    }

    #[test]
    fn with_rust_src_rule_revirtualizes_std_when_installed() {
        // Simulate an installed rust-src component: {sysroot}/lib/rustlib/src/rust
        // exists on disk so the rule canonicalizes.
        let tmp = TempDir::new().unwrap();
        let sysroot = tmp.path();
        let rust_src = sysroot.join("lib").join("rustlib").join("src").join("rust");
        std::fs::create_dir_all(&rust_src).unwrap();

        let n = PathNormalizer::from_env(None).with_rust_src_rule(Some(sysroot), Some("abc123"));
        let args = n.remap_args();

        // Build the query from the SAME canonical form the rule stored (not raw
        // `canonicalize()`, which on Windows yields a `\\?\C:\...` verbatim path
        // with backslashes that would not match the rule's stripped prefix).
        let prefix = canonical_string(&rust_src).expect("rust-src canonicalizes");

        // A std file path composes to the upstream virtual form the profiler
        // already fetches from github.com/rust-lang/rust.
        assert_eq!(
            apply_last_match(&args, &format!("{prefix}/library/core/src/ptr/mod.rs")),
            "/rustc/abc123/library/core/src/ptr/mod.rs"
        );
    }

    #[test]
    fn configured_root_wins_over_rust_src_on_key_and_remap_sides() {
        let tmp = TempDir::new().unwrap();
        let sysroot = tmp.path().join("sysroot");
        let rust_src = sysroot.join("lib").join("rustlib").join("src").join("rust");
        std::fs::create_dir_all(&rust_src).unwrap();

        let base = canonical_string(tmp.path()).unwrap();
        let source = format!("{base}/sysroot/lib/rustlib/src/rust/library/core/src/lib.rs");
        let normalizer = PathNormalizer::empty()
            .with_base_dirs(std::slice::from_ref(&base))
            .with_rust_src_rule(Some(&sysroot), Some("abc123"));

        assert_eq!(
            normalizer.normalize(&source),
            "<BASE_DIR_0>/sysroot/lib/rustlib/src/rust/library/core/src/lib.rs"
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), &source),
            "/kache/base-dir-0/sysroot/lib/rustlib/src/rust/library/core/src/lib.rs"
        );
    }

    #[test]
    fn with_rust_src_rule_is_noop_without_sysroot_hash_or_installed_src() {
        let base = PathNormalizer::from_env(None).remap_args().len();
        // No sysroot, no hash, or a sysroot whose rust-src dir does not exist
        // (component not installed) all leave the rule set unchanged.
        assert_eq!(
            PathNormalizer::from_env(None)
                .with_rust_src_rule(None, Some("abc"))
                .remap_args()
                .len(),
            base
        );
        assert_eq!(
            PathNormalizer::from_env(None)
                .with_rust_src_rule(Some(Path::new("/x")), None)
                .remap_args()
                .len(),
            base
        );
        assert_eq!(
            PathNormalizer::from_env(None)
                .with_rust_src_rule(
                    Some(Path::new("/definitely/nonexistent/sysroot")),
                    Some("abc")
                )
                .remap_args()
                .len(),
            base
        );
    }

    #[test]
    fn normalize_replaces_all_occurrences_of_same_prefix() {
        // String::replace replaces every match, not just the first.
        // Realistic case: a RUSTFLAGS value with multiple `-L` flags
        // pointing at different subdirs of the same workspace.
        let n = pn_with_rules(vec![("/ws", "<W>")]);
        let input = "-L /ws/lib -L /ws/build/deps -L /ws/extra";
        let out = n.normalize(input);
        assert_eq!(out, "-L <W>/lib -L <W>/build/deps -L <W>/extra");
    }

    #[test]
    fn normalize_handles_input_equal_to_prefix() {
        // Boundary: input has nothing after the prefix. Should
        // become exactly the sentinel — no leftover bytes.
        let n = pn_with_rules(vec![("/ws", "<W>")]);
        assert_eq!(n.normalize("/ws"), "<W>");
    }

    #[test]
    fn normalize_chains_multiple_distinct_prefixes_in_one_input() {
        // Real RUSTFLAGS-style input mixing workspace and cargo home
        // references. Both rules apply, each to its own substring.
        let n = pn_with_rules(vec![("/ws", "<W>"), ("/home/u/.cargo", "<C>")]);
        let input = "-L /ws/lib -L /home/u/.cargo/registry/src/foo";
        let out = n.normalize(input);
        assert_eq!(out, "-L <W>/lib -L <C>/registry/src/foo");
    }

    #[test]
    fn most_specific_prefix_wins_when_nested() {
        // The classic "workspace lives inside home" case. PathNormalizer's
        // rule order is most-specific first, so when normalize sweeps
        // sequentially, the workspace prefix matches and replaces the
        // input BEFORE the home prefix gets a chance — the resulting
        // string starts with `<W>` not `<H>/projects/...`.
        let n = pn_with_rules(vec![("/home/u/projects/ws", "<W>"), ("/home/u", "<H>")]);
        let input = "/home/u/projects/ws/src/lib.rs";
        let out = n.normalize(input);
        assert_eq!(out, "<W>/src/lib.rs");
        // Sibling path that ISN'T inside the workspace falls through
        // to the home rule, as expected.
        let sibling = "/home/u/other/foo.rs";
        assert_eq!(n.normalize(sibling), "<H>/other/foo.rs");
    }

    #[test]
    fn normalize_is_idempotent_on_already_sentinelized_input() {
        // Critical safety: running normalize twice should be a
        // no-op for the second pass. Sentinels are angle-bracketed
        // (`<HOME>`, `<WORKSPACE>`) and POSIX paths don't use
        // angles, so a sentinel can't be a prefix of any rule. If
        // a future change ever picked sentinel strings that happen
        // to look like real paths, this test fires.
        let n = pn_with_rules(vec![("/home/u", "<HOME>"), ("/workspace", "<WORKSPACE>")]);
        let input = "/home/u/projects/foo /workspace/src/main.rs";
        let once = n.normalize(input);
        let twice = n.normalize(&once);
        assert_eq!(once, twice, "normalize is not idempotent");
        assert!(once.contains("<HOME>"));
        assert!(once.contains("<WORKSPACE>"));
    }

    #[test]
    fn normalize_substring_match_is_documented_limitation() {
        // ACCEPTED LIMITATION: String::replace is byte-substring,
        // not path-component aware. A rule for `/home/u` will match
        // a partial path component like `/home/usr` (incorrectly
        // turning `/home/usr/foo` into `<HOME>r/foo`).
        //
        // In practice this doesn't bite because PathNormalizer's
        // rule prefixes always come from `Path::canonicalize()`,
        // which yields paths that end at a real directory boundary
        // — and consumers (cache_key inputs) almost always have a
        // separator immediately after a matched prefix. But if a
        // future caller starts with prefixes that don't end at
        // directory boundaries, this test documents the surprise
        // it would produce.
        let n = pn_with_rules(vec![("/home/u", "<H>")]);
        // Pathological input: `/home/usr/foo` contains `/home/u` as
        // a 7-byte substring (same first 7 chars), so replace fires
        // and leaves `sr/foo` behind. Semantically wrong if `/home/usr`
        // is supposed to be a different user — but the input was
        // already a bare-substring match, not a path-component match.
        assert_eq!(n.normalize("/home/usr/foo"), "<H>sr/foo");
        // The realistic case still works because cargo / canonicalize
        // produces paths with separators after the prefix.
        assert_eq!(n.normalize("/home/u/foo"), "<H>/foo");
    }

    #[test]
    fn normalize_handles_realistic_out_dir_value() {
        // End-to-end shape mirroring what `parse_env_dep_info`
        // would feed in for a real serde build:
        //   env_dep:OUT_DIR=/<workspace>/target/release/build/serde-XXX/out
        let n = pn_with_rules(vec![("/Users/alice/projects/myrepo", "<WORKSPACE>")]);
        let out_dir =
            "/Users/alice/projects/myrepo/target/release/build/serde-65d43fa14511931c/out";
        assert_eq!(
            n.normalize(out_dir),
            "<WORKSPACE>/target/release/build/serde-65d43fa14511931c/out"
        );
    }

    #[test]
    fn normalize_handles_realistic_rustflags_value() {
        // Real RUSTFLAGS shape with multiple link-search dirs, some
        // of which reference machine-local paths.
        let n = pn_with_rules(vec![
            ("/Users/alice/.cargo", "<CARGO_HOME>"),
            ("/Users/alice/projects/myrepo", "<WORKSPACE>"),
        ]);
        let flags = "-L /Users/alice/.cargo/registry/cache/foo \
                     -L /Users/alice/projects/myrepo/target/release/deps \
                     -C link-arg=-Wl,-rpath,/system/lib";
        let out = n.normalize(flags);
        // Both machine-local paths sentinelized.
        assert!(out.contains("<CARGO_HOME>/registry/cache/foo"));
        assert!(out.contains("<WORKSPACE>/target/release/deps"));
        // System path NOT in the rule list — passes through.
        assert!(out.contains("/system/lib"));
    }

    #[test]
    fn lowercase_drive_letter_handles_drive_root_alone() {
        // Edge case: input is just `C:\` or `C:` with nothing else.
        // Drive letter still gets lowercased; rest preserved.
        assert_eq!(lowercase_drive_letter("C:\\"), Some("c:\\".to_string()));
        assert_eq!(lowercase_drive_letter("C:"), Some("c:".to_string()));
        assert_eq!(lowercase_drive_letter("D:/"), Some("d:/".to_string()));
    }

    #[test]
    fn windows_variants_are_distinct_for_distinct_canonical_forms() {
        // Sanity: the four-variant expansion produces FOUR distinct
        // strings only when each form differs. If the canonical form
        // already has lowercase drive + forward slashes, no extra
        // variants are added (they'd be exact duplicates that dedup
        // would strip anyway).
        if !cfg!(windows) {
            return;
        }
        let mut rules = Vec::new();
        push_rule_with_variants(
            &mut rules,
            Some("c:/users/alice/.cargo".to_string()),
            "<CARGO_HOME>",
        );
        // The "canonical" we passed is already in the
        // lowercase-drive forward-slash form; backslash variant
        // should be added but not the lowercase-drive variant
        // (it's already lowercase).
        let prefixes: Vec<&str> = rules.iter().map(|r| r.prefix.as_str()).collect();
        assert!(prefixes.contains(&"c:/users/alice/.cargo"));
        assert!(prefixes.contains(&"c:\\users\\alice\\.cargo"));
        // No uppercase-drive variant — we didn't construct one.
        assert!(!prefixes.iter().any(|p| p.starts_with("C:")));
    }

    #[test]
    fn remap_args_emits_all_windows_variants_with_same_target() {
        // Each Windows shape variant becomes its own --remap-path-prefix flag,
        // all mapping to the same resolvable TARGET. rustc applies them with
        // last-match-wins; whichever variant the actual build path matches, the
        // target is identical.
        if !cfg!(windows) {
            return;
        }
        let mut rules = Vec::new();
        push_rule_with_variants(
            &mut rules,
            Some("C:\\Users\\Alice\\.cargo".to_string()),
            "<CARGO_HOME>",
        );
        let n = PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };
        let args = n.remap_args();
        // 4 variants, all mapping to the CARGO_HOME target (/kache/.cargo).
        assert_eq!(args.len(), 4);
        let target = flag_target_for("<CARGO_HOME>");
        for arg in &args {
            assert!(
                arg.ends_with(&format!("={target}")),
                "every variant maps to the same target {target:?}; got {arg:?}"
            );
        }
    }

    // ── Unicode safety ──────────────────────────────────────────
    //
    // The substring-match design uses byte-literal `String::replace`
    // (which is UTF-8 self-synchronizing — partial codepoint matches
    // can't happen). The drive-letter helper uses byte indexing
    // explicitly to stay panic-safe on inputs that start with a
    // multi-byte codepoint. These tests pin both contracts.

    #[test]
    fn lowercase_drive_letter_does_not_panic_on_multibyte_first_char() {
        // `É` is U+00C9, encoded as two bytes in UTF-8 (0xC3 0x89).
        // The earlier `&s[1..2]` slice would panic with
        // "not a char boundary" on byte 1 (which is inside É).
        // The byte-level check returns None cleanly.
        assert_eq!(lowercase_drive_letter("É:foo"), None);
        assert_eq!(lowercase_drive_letter("日本:"), None);
        assert_eq!(lowercase_drive_letter("é"), None); // too short for : check anyway
        // Sanity: the ASCII drive case still works.
        assert_eq!(lowercase_drive_letter("C:foo"), Some("c:foo".to_string()));
    }

    #[test]
    fn normalize_handles_unicode_paths_correctly() {
        // Realistic case: `/Users/José/.cargo`. The rule prefix and
        // input both use the SAME UTF-8 byte sequence (NFC form, the
        // typical state when the env var is set on macOS APFS).
        // String::replace works on bytes; UTF-8 is self-synchronizing
        // so partial matches inside multi-byte codepoints can't
        // happen.
        let n = pn_with_rules(vec![("/Users/José/.cargo", "<CARGO_HOME>")]);
        let input = "/Users/José/.cargo/registry/src/foo";
        assert_eq!(n.normalize(input), "<CARGO_HOME>/registry/src/foo");
    }

    #[test]
    fn normalize_matches_across_nfc_nfd_unicode_normalization_forms() {
        // The macOS NFC vs NFD case. `é` has two valid UTF-8
        // byte sequences:
        //   NFC: U+00E9         → 0xC3 0xA9       (2 bytes)
        //   NFD: U+0065 U+0301  → 0x65 0xCC 0x81  (3 bytes)
        // String::replace is byte-literal so the two forms don't
        // match each other directly. PathNormalizer normalizes both
        // sides to NFC before matching, so a rule built from a path
        // returned in NFD (HFS+ legacy / some macOS APIs) still
        // matches an input string in NFC (typical env-var form).
        let nfc_prefix = "/Users/Jos\u{00E9}/.cargo"; // single codepoint é
        let nfd_input = "/Users/Jos\u{0065}\u{0301}/.cargo/registry/foo"; // e + combining acute

        // Sanity: the byte sequences differ.
        assert_ne!(
            nfc_prefix.as_bytes(),
            &nfd_input.as_bytes()[..nfc_prefix.len()]
        );

        // Rule prefix in NFC form — `from_env`'s `canonical_string`
        // would have produced this. Input arrives in NFD; normalize
        // converts it to NFC before matching, so the substring hit
        // fires.
        let n = pn_with_rules(vec![(nfc_prefix, "<CARGO_HOME>")]);
        let out = n.normalize(nfd_input);
        assert_eq!(out, "<CARGO_HOME>/registry/foo");

        // Symmetric: NFC input also matches.
        let nfc_input = "/Users/Jos\u{00E9}/.cargo/registry/bar";
        assert_eq!(n.normalize(nfc_input), "<CARGO_HOME>/registry/bar");
    }

    #[test]
    fn strip_verbatim_prefix_removes_extended_length_marker() {
        // The #201 bug: canonicalize returns `\\?\C:\...` on Windows, so
        // a rule prefix never substring-matched the plain `C:\...` paths
        // cargo emits → OUT_DIR leaked into the cache key.
        assert_eq!(strip_verbatim_prefix(r"\\?\C:\proj\out"), r"C:\proj\out");
        // UNC verbatim collapses back to its `\\server\share` form.
        assert_eq!(
            strip_verbatim_prefix(r"\\?\UNC\server\share\x"),
            r"\\server\share\x"
        );
        // Plain paths (and all Unix paths) pass through untouched.
        assert_eq!(strip_verbatim_prefix(r"C:\proj\out"), r"C:\proj\out");
        assert_eq!(strip_verbatim_prefix("/home/u/proj"), "/home/u/proj");
    }

    #[test]
    fn filesystem_root_prefix_distinguishes_unc_share_roots() {
        for root in [
            "//server/share",
            "//server/share/",
            r"\\server\share",
            r"\\server\share\",
            r"\\?\UNC\server\share",
        ] {
            assert!(is_filesystem_root_prefix(root), "{root:?}");
        }
        for narrower_or_incomplete in [
            "//server",
            "//server/",
            "///share",
            "//server/share/app",
            r"\\server\share\app",
        ] {
            assert!(
                !is_filesystem_root_prefix(narrower_or_incomplete),
                "{narrower_or_incomplete:?}"
            );
        }
    }

    #[test]
    fn os_path_spellings_keep_raw_and_plain_verbatim_windows_forms() {
        assert_eq!(
            os_path_spellings(Path::new(r"\\?\C:\Work\Root")),
            vec![r"\\?\C:\Work\Root".to_string(), r"C:\Work\Root".to_string()]
        );
        assert_eq!(
            os_path_spellings(Path::new(r"\\?\UNC\server\share\Root")),
            vec![
                r"\\?\UNC\server\share\Root".to_string(),
                r"\\server\share\Root".to_string()
            ]
        );
    }

    #[test]
    fn canonical_string_normalizes_to_nfc() {
        // Rule construction must produce NFC-form prefixes so that
        // the NFC normalization in `normalize` can match. Even if
        // the underlying path uses non-NFC bytes (which canonicalize
        // may return on macOS), the stored prefix must be NFC.
        let dir = TempDir::new().unwrap();
        let nfc_name = "Jos\u{00E9}";
        let subdir = dir.path().join(nfc_name);
        std::fs::create_dir(&subdir).unwrap();

        let result = canonical_string(&subdir).expect("canonicalize should succeed");
        // NFC contract: re-normalizing gives the same string.
        let renormalized: String = result.nfc().collect();
        assert_eq!(
            result, renormalized,
            "canonical_string output must be in NFC form, got {result:?}"
        );
    }

    #[test]
    fn normalize_preserves_unicode_outside_matched_prefix() {
        // The "no transformation of unmatched bytes" contract
        // extends to unicode: a code point that contains `\` or `/`
        // bytes shouldn't get partially mangled. UTF-8 reserves
        // bytes 0x00-0x7F for ASCII and uses 0xC0-0xFD as multi-byte
        // markers, so `/` (0x2F) and `\` (0x5C) only appear as
        // themselves — no risk of accidental separator detection
        // mid-codepoint. This test pins it by example.
        let n = pn_with_rules(vec![("/ws", "<W>")]);
        let input = "/ws/José/中文/файл.rs"; // Latin / CJK / Cyrillic
        let out = n.normalize(input);
        assert_eq!(out, "<W>/José/中文/файл.rs");
    }

    #[test]
    fn from_env_construction_is_deterministic() {
        // Two normalizers built from the same env should have
        // identical rule lists — prerequisite for cross-machine
        // cache key consistency. (If this ever flakes, something
        // in `from_env` reads non-deterministic state.)
        let dir = TempDir::new().unwrap();
        let n1 = PathNormalizer::from_env(Some(dir.path()));
        let n2 = PathNormalizer::from_env(Some(dir.path()));
        let p1: Vec<(String, String)> = n1
            .rules
            .iter()
            .map(|r| (r.prefix.clone(), r.key_sentinel.clone()))
            .collect();
        let p2: Vec<(String, String)> = n2
            .rules
            .iter()
            .map(|r| (r.prefix.clone(), r.key_sentinel.clone()))
            .collect();
        assert_eq!(p1, p2);
    }

    #[test]
    fn configured_base_dirs_are_order_independent_and_longest_match_wins() {
        let dir = TempDir::new().unwrap();
        let parent = dir.path().join("container");
        let child = parent.join("work");
        std::fs::create_dir_all(&child).unwrap();

        let parent_cfg = parent.to_string_lossy().into_owned();
        let child_cfg = child.to_string_lossy().into_owned();
        let forward =
            PathNormalizer::empty().with_base_dirs(&[parent_cfg.clone(), child_cfg.clone()]);
        let reverse = PathNormalizer::empty().with_base_dirs(&[child_cfg, parent_cfg]);
        let input = format!(
            "{}/src/lib.rs",
            canonical_string(&child).expect("child canonicalizes")
        );

        assert_eq!(forward.normalize(&input), reverse.normalize(&input));
        assert_eq!(forward.normalize(&input), "<BASE_DIR_1>/src/lib.rs");
        assert_eq!(forward.configured_base_dir_count(), 2);
    }

    #[test]
    fn configured_base_dir_requires_path_component_boundaries() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().join("work");
        std::fs::create_dir_all(&root).unwrap();
        let root = root.to_string_lossy().into_owned();
        let normalizer = PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&root));

        assert_eq!(
            normalizer.normalize(format!("{root}/src {root}space/src /opt{root}/src")),
            format!("<BASE_DIR_0>/src {root}space/src /opt{root}/src")
        );
        let backslash_path = format!(r"{root}\src");
        let expected_backslash_path = if cfg!(windows) {
            r"<BASE_DIR_0>\src".to_string()
        } else {
            backslash_path.clone()
        };
        assert_eq!(
            normalizer.normalize(&backslash_path),
            expected_backslash_path
        );
        assert_eq!(
            normalizer.normalize(format!("-L{root}/lib key={root}/src")),
            "-L<BASE_DIR_0>/lib key=<BASE_DIR_0>/src"
        );
        assert_eq!(
            normalizer.normalize(format!("-L\u{1f}{root}/lib")),
            "-L\u{1f}<BASE_DIR_0>/lib"
        );
    }

    #[test]
    fn configured_windows_root_has_slash_and_drive_case_variants() {
        let normalizer = PathNormalizer::empty().with_base_dirs(&["C:/Build/Root".to_string()]);
        assert_eq!(
            normalizer.normalize(r"c:\Build\Root\src\main.c"),
            r"<BASE_DIR_0>\src\main.c"
        );
    }

    #[test]
    fn configured_posix_root_does_not_gain_windows_aliases() {
        let normalizer = PathNormalizer::empty().with_base_dirs(&["/snap".to_string()]);
        assert!(normalizer.rules.iter().all(|rule| rule.prefix != r"\snap"));
        assert_eq!(normalizer.normalize("/snap/pkg"), "<BASE_DIR_0>/pkg");
        assert_eq!(normalizer.normalize("C:/snap/pkg"), "C:/snap/pkg");
        assert_eq!(normalizer.normalize(r"C:\snap\pkg"), r"C:\snap\pkg");
    }

    #[test]
    fn configured_path_canonicalization_is_native_syntax_only() {
        assert!(is_native_configured_path_for("/work", false));
        assert!(!is_native_configured_path_for("C:/work", false));
        assert!(!is_native_configured_path_for("//server/share", false));

        assert!(!is_native_configured_path_for("/work", true));
        assert!(is_native_configured_path_for("C:/work", true));
        assert!(is_native_configured_path_for(r"\\server\share", true));
    }

    #[cfg(windows)]
    #[test]
    fn configured_plain_root_owns_verbatim_canonical_sources_and_depinfo() {
        let producer = TempDir::new().unwrap();
        let consumer = TempDir::new().unwrap();
        let producer_root = producer.path().join("Configured Root");
        let consumer_root = consumer.path().join("Configured Root");
        std::fs::create_dir_all(producer_root.join("src")).unwrap();
        std::fs::create_dir_all(consumer_root.join("src")).unwrap();
        std::fs::write(producer_root.join("src/value.rs"), "pub const V: u8 = 1;").unwrap();

        let producer_cfg = producer_root.to_string_lossy().into_owned();
        let consumer_cfg = consumer_root.to_string_lossy().into_owned();
        let producer_normalizer =
            PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&producer_cfg));
        let consumer_normalizer =
            PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&consumer_cfg));
        let canonical_source = producer_root.join("src/value.rs").canonicalize().unwrap();

        assert_eq!(
            producer_normalizer
                .source_path_identity(&canonical_source)
                .unwrap(),
            b"<BASE_DIR_0>/src\\value.rs"
        );
        assert_eq!(
            apply_last_match(
                &producer_normalizer.remap_args(),
                canonical_source.to_str().unwrap()
            ),
            "/kache/base-dir-0\\src\\value.rs"
        );

        let producer_roots = producer_normalizer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let consumer_roots = consumer_normalizer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let raw = format!(r"C:\target\demo.d: {}", canonical_source.display());
        let stored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &raw,
            Path::new(r"C:\target"),
            Path::new(r"C:\work"),
            None,
            &producer_roots,
            crate::link::DepInfoMode::Relativize,
        );
        assert!(
            stored.contains("__kache_base_dir_0__/src\\value.rs"),
            "{stored}"
        );
        let restored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &stored,
            Path::new(r"C:\target"),
            Path::new(r"C:\work"),
            None,
            &consumer_roots,
            crate::link::DepInfoMode::Expand,
        );
        let expected = format!(r"{}\src\value.rs", consumer_root.display()).replace(' ', "\\ ");
        assert!(restored.contains(&expected), "{restored}");
        assert!(!restored.contains(&producer_root.to_string_lossy().into_owned()));
    }

    #[test]
    fn configured_root_wins_consistently_in_key_and_rustc_remap() {
        let cargo_home = "/sandbox/.cargo";
        let path = "/sandbox/.cargo/registry/src/pkg/lib.rs";
        let normalizer = pn_with_rules(vec![(cargo_home, "<CARGO_HOME>")])
            .with_base_dirs(&["/sandbox".to_string()]);

        assert_eq!(
            normalizer.normalize(path),
            "<BASE_DIR_0>/.cargo/registry/src/pkg/lib.rs"
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), path),
            "/kache/base-dir-0/.cargo/registry/src/pkg/lib.rs"
        );
        assert_eq!(
            normalizer.source_path_identity(Path::new(path)).unwrap(),
            b"<BASE_DIR_0>/.cargo/registry/src/pkg/lib.rs"
        );
    }

    #[test]
    fn legacy_base_dir_is_a_complete_owner_and_rejects_empty_or_root() {
        let dir = TempDir::new().unwrap();
        let base = dir.path().join("legacy");
        let source = base.join("src/lib.rs");
        std::fs::create_dir_all(source.parent().unwrap()).unwrap();
        std::fs::write(&source, "pub const VALUE: u8 = 1;").unwrap();

        let mut rules = Vec::new();
        let mut source_restore_roots = Vec::new();
        push_legacy_base_dir_rules(
            &mut rules,
            &mut source_restore_roots,
            Some(base.as_os_str()),
        );
        let normalizer = PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots,
            path_only_env_vars: Vec::new(),
        };
        let relative = source.strip_prefix(&base).unwrap().to_string_lossy();
        assert_eq!(
            normalizer.source_path_identity(&source).unwrap(),
            format!("<BASE_DIR>/{relative}").as_bytes()
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), source.to_str().unwrap()),
            format!(
                "{}{}",
                flag_target_for("<BASE_DIR>"),
                source
                    .to_str()
                    .unwrap()
                    .strip_prefix(base.to_str().unwrap())
                    .unwrap()
            )
        );
        assert!(normalizer.depinfo_source_roots().iter().any(|root| {
            root.root == base
                && root.key_sentinel == "<BASE_DIR>"
                && root.depinfo_sentinel == "__kache_base_dir__/"
        }));

        let filesystem_root = if cfg!(windows) {
            Path::new(r"C:\")
        } else {
            Path::new("/")
        };
        for invalid in [std::ffi::OsStr::new(""), filesystem_root.as_os_str()] {
            let mut rules = Vec::new();
            let mut restore_roots = Vec::new();
            push_legacy_base_dir_rules(&mut rules, &mut restore_roots, Some(invalid));
            assert!(rules.is_empty());
            assert!(restore_roots.is_empty());
        }
    }

    #[cfg(windows)]
    #[test]
    fn legacy_base_dir_owns_verbatim_canonical_sources() {
        let dir = TempDir::new().unwrap();
        let base = dir.path().join("Legacy Root");
        let source = base.join("src/value.rs");
        std::fs::create_dir_all(source.parent().unwrap()).unwrap();
        std::fs::write(&source, "pub const VALUE: u8 = 1;").unwrap();

        let mut rules = Vec::new();
        let mut source_restore_roots = Vec::new();
        push_legacy_base_dir_rules(
            &mut rules,
            &mut source_restore_roots,
            Some(base.as_os_str()),
        );
        let normalizer = PathNormalizer {
            rules,
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots,
            path_only_env_vars: Vec::new(),
        };
        let canonical_source = source.canonicalize().unwrap();
        assert_eq!(
            normalizer.source_path_identity(&canonical_source).unwrap(),
            b"<BASE_DIR>/src\\value.rs"
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), canonical_source.to_str().unwrap()),
            "/kache/base-dir\\src\\value.rs"
        );
        let canonical_base = base.canonicalize().unwrap();
        assert!(normalizer.depinfo_source_roots().iter().any(|root| {
            root.root == canonical_base && root.depinfo_sentinel == "__kache_base_dir__/"
        }));
    }

    #[test]
    fn legacy_base_dir_exposes_a_depinfo_restore_descriptor() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_string_lossy().into_owned();
        let normalizer = pn_with_rules(vec![(&root, "<BASE_DIR>")]);
        let roots = normalizer.depinfo_source_roots();

        assert_eq!(roots.len(), 1);
        assert_eq!(roots[0].root, dir.path());
        assert_eq!(roots[0].key_sentinel, "<BASE_DIR>");
        assert_eq!(roots[0].depinfo_sentinel, "__kache_base_dir__/");
        assert_eq!(roots[0].priority, flag_emit_rank("<BASE_DIR>"));
    }

    #[test]
    fn external_target_exposes_a_distinct_source_restore_descriptor() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_string_lossy().into_owned();
        let normalizer = pn_with_rules(vec![(&root, "<TARGET>")]);
        let roots = normalizer.depinfo_source_roots();

        assert_eq!(roots.len(), 1);
        assert_eq!(roots[0].root, dir.path());
        assert_eq!(roots[0].key_sentinel, "<TARGET>");
        assert_eq!(roots[0].depinfo_sentinel, "__kache_target_rule__/");
        assert_eq!(roots[0].priority, flag_emit_rank("<TARGET>"));
    }

    #[test]
    fn every_source_sentinel_has_a_distinct_depinfo_sentinel() {
        // `depinfo_source_roots` walks exactly this sentinel list. A source
        // sentinel missing its dep-info mapping silently drops that root from
        // the portable rewrite, so the stored `.d` keeps a live local path and
        // a relocated hit validates against the donor's tree.
        let mapped = [
            ("<CWD>", "__kache_cwd__/"),
            ("<WORKSPACE>", "__kache_workspace__/"),
            ("<TARGET>", "__kache_target_rule__/"),
            ("<CARGO_HOME>", "__kache_cargo_home__/"),
            ("<BASE_DIR>", "__kache_base_dir__/"),
            ("<RUSTUP_HOME>", "__kache_rustup_home__/"),
            ("<HOME>", "__kache_home__/"),
            ("<APPDATA>", "__kache_appdata__/"),
            ("<LOCALAPPDATA>", "__kache_localappdata__/"),
            ("<PROGRAMFILES>", "__kache_programfiles__/"),
            ("<TMPDIR>", "__kache_tmpdir__/"),
        ];
        for (source_sentinel, expected) in mapped {
            assert_eq!(
                depinfo_sentinel_for_source(source_sentinel).as_deref(),
                Some(expected),
                "{source_sentinel} must map to a portable dep-info sentinel"
            );
        }

        let distinct: std::collections::HashSet<&str> =
            mapped.iter().map(|(_, sentinel)| *sentinel).collect();
        assert_eq!(
            distinct.len(),
            mapped.len(),
            "two source roots sharing a dep-info sentinel would expand to the wrong tree"
        );

        // `<RUST_SRC>` is remapped for debug info but is never a restorable
        // source root, and an unknown sentinel must not invent one.
        assert_eq!(depinfo_sentinel_for_source("<RUST_SRC>"), None);
        assert_eq!(depinfo_sentinel_for_source("<NOT_A_SENTINEL>"), None);

        // Configured slots are numbered rather than named.
        assert_eq!(
            depinfo_sentinel_for_source("<BASE_DIR_2>").as_deref(),
            Some("__kache_base_dir_2__/")
        );
    }

    #[test]
    fn a_second_target_root_lands_between_its_higher_and_lower_ranked_peers() {
        // `with_target_dir` splices the new rules at the one position that
        // preserves rustc's precedence: after every rule that outranks
        // `<TARGET>` and after an equal-ranked peer (`from_env` already
        // installed one when `CARGO_TARGET_DIR` is set), but before anything
        // that ranks below it. `normalize` applies rules in list order, so
        // landing on either side of that slot silently changes which root owns
        // a generated source — and with it the cache key.
        let dir = TempDir::new().unwrap();
        let base = dir.path().canonicalize().unwrap();
        let outer_target = base.join("target");
        let nested = outer_target.join("wasm32-unknown-unknown");
        fs::create_dir_all(&nested).unwrap();
        let workspace_prefix = base.join("workspace").to_string_lossy().into_owned();
        let outer_prefix = outer_target.to_string_lossy().into_owned();
        let tmpdir_prefix = base.join("tmp").to_string_lossy().into_owned();

        // Ranks: <WORKSPACE> 4 > <TARGET> 3 > <TMPDIR> 0.
        let normalizer = pn_with_rules(vec![
            (&workspace_prefix, "<WORKSPACE>"),
            (&outer_prefix, "<TARGET>"),
            (&tmpdir_prefix, "<TMPDIR>"),
        ])
        .with_target_dir(Some(&nested));

        let spellings = || {
            normalizer
                .rules
                .iter()
                .map(|rule| rule.prefix.clone())
                .collect::<Vec<_>>()
        };
        let at = |prefix: &str| {
            normalizer
                .rules
                .iter()
                .position(|rule| rule.prefix == prefix)
                .unwrap_or_else(|| panic!("{prefix} survives, got {:?}", spellings()))
        };
        let nested_at = normalizer
            .rules
            .iter()
            .position(|rule| {
                rule.prefix.starts_with(&outer_prefix) && rule.prefix.len() > outer_prefix.len()
            })
            .expect("the nested target rule is added");

        assert!(
            at(&workspace_prefix) < nested_at,
            "a higher-ranked root must stay ahead of a new <TARGET>, got {:?}",
            spellings()
        );
        assert!(
            at(&outer_prefix) < nested_at,
            "the established <TARGET> peer must keep normalizing first, got {:?}",
            spellings()
        );
        assert!(
            nested_at < at(&tmpdir_prefix),
            "a lower-ranked root must not consume the target first, got {:?}",
            spellings()
        );

        let generated = nested.join("generated.rs").to_string_lossy().into_owned();
        let suffix = generated
            .strip_prefix(&outer_prefix)
            .expect("the nested target is under the outer target");
        assert_eq!(
            normalizer.normalize(&generated),
            format!("<TARGET>{suffix}"),
            "the outer target owns the prefix, so the nested segment stays in the key"
        );
    }

    #[test]
    fn depinfo_restore_root_prefers_the_designated_spelling_over_the_first_alias() {
        // `from_env` records one restore root per source sentinel in push order
        // (`<CWD>`, `<WORKSPACE>`, then `<TARGET>`), so a sentinel's designated
        // entry is routinely preceded by a different sentinel's. Selecting the
        // wrong entry falls back to whichever alias rule happens to come first,
        // which rewrites dep-info against a spelling the build never used.
        let dir = TempDir::new().unwrap();
        let base = dir.path().canonicalize().unwrap();
        let alias = base.join("alias-target");
        let designated = base.join("designated-target");
        let workspace = base.join("workspace");
        for path in [&alias, &designated, &workspace] {
            fs::create_dir(path).unwrap();
        }
        let rule = |path: &Path, sentinel: &str| Rule {
            prefix: path.to_string_lossy().into_owned(),
            key_sentinel: sentinel.to_string(),
            source_sentinel: sentinel.to_string(),
            flag_target: flag_target_for(sentinel),
        };

        let normalizer = PathNormalizer {
            // The alias rule comes first, so the fallback scan would pick it.
            rules: vec![
                rule(&alias, "<TARGET>"),
                rule(&designated, "<TARGET>"),
                rule(&workspace, "<WORKSPACE>"),
            ],
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: vec![
                ("<WORKSPACE>".to_string(), workspace.clone()),
                ("<TARGET>".to_string(), designated.clone()),
            ],
            path_only_env_vars: Vec::new(),
        };

        let target_root = normalizer
            .depinfo_source_roots()
            .into_iter()
            .find(|root| root.key_sentinel == "<TARGET>")
            .expect("the target sentinel has an existing native root");
        assert_eq!(
            target_root.root, designated,
            "the designated <TARGET> spelling must win over the earlier alias rule"
        );
    }

    #[test]
    fn configured_slot_does_not_duplicate_an_identical_legacy_owner() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_string_lossy().into_owned();
        let normalizer =
            pn_with_rules(vec![(&root, "<BASE_DIR>")]).with_base_dirs(std::slice::from_ref(&root));
        let roots = normalizer.depinfo_source_roots();

        assert_eq!(normalizer.configured_base_dir_count(), 1);
        assert_eq!(roots.len(), 1);
        assert_eq!(roots[0].key_sentinel, "<BASE_DIR>");
        assert_eq!(roots[0].depinfo_sentinel, "__kache_base_dir__/");
        assert!(
            !roots
                .iter()
                .any(|descriptor| descriptor.key_sentinel == "<BASE_DIR_0>")
        );
    }

    #[test]
    fn source_identity_matches_rustc_semantic_root_precedence() {
        let normalizer = pn_with_rules(vec![
            ("/workspace/target-a", "<TARGET>"),
            ("/workspace", "<WORKSPACE>"),
        ]);
        let source = Path::new("/workspace/target-a/generated.rs");

        assert_eq!(
            normalizer.source_path_identity(source).unwrap(),
            b"<WORKSPACE>/target-a/generated.rs"
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), source.to_str().unwrap()),
            format!("{}/target-a/generated.rs", workspace_flag_target())
        );
    }

    #[test]
    fn source_identity_distinguishes_member_cwd_from_workspace_root() {
        let normalizer = PathNormalizer {
            rules: vec![
                Rule {
                    prefix: "/repo/member".to_string(),
                    key_sentinel: "<WORKSPACE>".to_string(),
                    source_sentinel: "<CWD>".to_string(),
                    flag_target: workspace_flag_target().to_string(),
                },
                Rule {
                    prefix: "/repo".to_string(),
                    key_sentinel: "<WORKSPACE>".to_string(),
                    source_sentinel: "<WORKSPACE>".to_string(),
                    flag_target: workspace_flag_target().to_string(),
                },
            ],
            configured_base_dir_count: 0,
            configured_source_root_groups: Vec::new(),
            source_restore_roots: Vec::new(),
            path_only_env_vars: Vec::new(),
        };

        assert_eq!(
            normalizer
                .source_path_identity(Path::new("/repo/member/value.rs"))
                .unwrap(),
            b"<CWD>/value.rs"
        );
        assert_eq!(
            normalizer
                .source_path_identity(Path::new("/repo/value.rs"))
                .unwrap(),
            b"<WORKSPACE>/value.rs"
        );
    }

    #[cfg(unix)]
    #[test]
    fn automatic_workspace_root_round_trips_lexical_and_canonical_spellings() {
        let dir = TempDir::new().unwrap();
        let real = dir.path().join("real/workspace");
        let link = dir.path().join("workspace-link");
        std::fs::create_dir_all(real.join("src")).unwrap();
        std::os::unix::fs::symlink(&real, &link).unwrap();

        let normalizer = PathNormalizer::from_env(Some(&link));
        let lexical = link.join("src/lib.rs");
        let canonical = real.canonicalize().unwrap().join("src/lib.rs");

        for source in [&lexical, &canonical] {
            assert_eq!(
                normalizer.source_path_identity(source).unwrap(),
                b"<WORKSPACE>/src/lib.rs"
            );
            assert_eq!(
                apply_last_match(&normalizer.remap_args(), source.to_str().unwrap()),
                format!("{}/src/lib.rs", workspace_flag_target())
            );
        }

        let roots = normalizer.depinfo_source_roots();
        let workspace_roots = roots
            .iter()
            .filter(|root| root.depinfo_sentinel == "__kache_workspace__/")
            .map(|root| root.root.as_path())
            .collect::<Vec<_>>();
        assert_eq!(workspace_roots.first().copied(), Some(link.as_path()));
        assert!(workspace_roots.contains(&real.canonicalize().unwrap().as_path()));

        let depinfo_roots = roots
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let target = dir.path().join("target");
        let raw = format!("{}/demo.d: {}\n", target.display(), canonical.display());
        let stored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &raw,
            &target,
            &link,
            Some(&link),
            &depinfo_roots,
            crate::link::DepInfoMode::Relativize,
        );
        assert!(
            stored.contains("__kache_workspace__/src/lib.rs"),
            "{stored}"
        );
        let restored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &stored,
            &target,
            &link,
            Some(&link),
            &depinfo_roots,
            crate::link::DepInfoMode::Expand,
        );
        assert!(restored.contains(&format!("{}/src/lib.rs", link.display())));
        assert!(!restored.contains(&format!("{}/src/lib.rs", real.display())));
    }

    #[cfg(unix)]
    #[test]
    fn configured_ancestor_keeps_a_winning_workspace_canonical_alias() {
        let dir = TempDir::new().unwrap();
        let producer_configured = dir.path().join("producer/configured");
        let consumer_configured = dir.path().join("consumer/configured");
        let producer_link = producer_configured.join("workspace");
        let consumer_link = consumer_configured.join("workspace");
        let producer_real = dir.path().join("producer-real/workspace");
        let consumer_real = dir.path().join("consumer-real/workspace");
        std::fs::create_dir_all(producer_real.join("src")).unwrap();
        std::fs::create_dir_all(consumer_real.join("src")).unwrap();
        std::fs::create_dir_all(&producer_configured).unwrap();
        std::fs::create_dir_all(&consumer_configured).unwrap();
        std::os::unix::fs::symlink(&producer_real, &producer_link).unwrap();
        std::os::unix::fs::symlink(&consumer_real, &consumer_link).unwrap();

        let producer = PathNormalizer::from_env(Some(&producer_link))
            .with_base_dirs(&[producer_configured.to_string_lossy().into_owned()]);
        let consumer = PathNormalizer::from_env(Some(&consumer_link))
            .with_base_dirs(&[consumer_configured.to_string_lossy().into_owned()]);
        let producer_canonical = producer_real.canonicalize().unwrap();
        let consumer_canonical = consumer_real.canonicalize().unwrap();
        let producer_source = producer_canonical.join("src/lib.rs");
        assert_eq!(
            producer.source_path_identity(&producer_source).unwrap(),
            b"<WORKSPACE>/src/lib.rs"
        );

        let producer_roots = producer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        assert!(producer_roots.iter().any(|(root, sentinel, _)| {
            root == &producer_canonical && sentinel == "__kache_workspace__/"
        }));
        let target = producer_link.join("target");
        let raw = format!(
            "{}/demo.d: {}\n",
            target.display(),
            producer_source.display()
        );
        let stored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &raw,
            &target,
            &producer_link,
            Some(&producer_link),
            &producer_roots,
            crate::link::DepInfoMode::Relativize,
        );
        assert!(
            stored.contains("__kache_workspace__/src/lib.rs"),
            "{stored}"
        );

        let consumer_roots = consumer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let restored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &stored,
            &consumer_link.join("target"),
            &consumer_link,
            Some(&consumer_link),
            &consumer_roots,
            crate::link::DepInfoMode::Expand,
        );
        assert!(restored.contains(&format!("{}/src/lib.rs", consumer_canonical.display())));
        assert!(!restored.contains(&producer_canonical.to_string_lossy().into_owned()));
    }

    #[test]
    fn argv_target_dir_owns_generated_sources_without_a_workspace_root() {
        let dir = TempDir::new().unwrap();
        let target = dir.path().join("target");
        let generated = target.join("release/build/serde-core/out/private.rs");
        std::fs::create_dir_all(generated.parent().unwrap()).unwrap();
        std::fs::write(&generated, "pub const PRIVATE: bool = true;\n").unwrap();

        let normalizer = PathNormalizer::empty().with_target_dir(Some(&target));
        assert_eq!(
            normalizer.source_path_identity(&generated).unwrap(),
            b"<TARGET>/release/build/serde-core/out/private.rs"
        );
        assert!(normalizer.depinfo_source_roots().iter().any(|root| {
            root.root == target && root.depinfo_sentinel == "__kache_target_rule__/"
        }));
        assert!(
            normalizer
                .remap_args()
                .iter()
                .any(|arg| arg.contains("=/kache/target"))
        );
    }

    #[cfg(unix)]
    #[test]
    fn canonical_filesystem_root_is_never_added_as_an_alias() {
        let dir = TempDir::new().unwrap();
        let link = dir.path().join("root-link");
        std::os::unix::fs::symlink("/", &link).unwrap();

        let mut legacy_rules = Vec::new();
        let mut restore_roots = Vec::new();
        push_legacy_base_dir_rules(
            &mut legacy_rules,
            &mut restore_roots,
            Some(link.as_os_str()),
        );
        assert!(legacy_rules.iter().all(|rule| rule.prefix != "/"));

        let configured =
            PathNormalizer::empty().with_base_dirs(&[link.to_string_lossy().into_owned()]);
        assert!(configured.rules.iter().all(|rule| rule.prefix != "/"));
        assert!(
            configured
                .source_path_identity(Path::new("/etc/passwd"))
                .is_none()
        );
    }

    #[test]
    fn source_identity_stays_local_for_roots_without_depinfo_restore_ownership() {
        let normalizer = pn_with_rules(vec![("/toolchain/rust", "<RUST_SRC>")]);
        assert!(
            normalizer
                .source_path_identity(Path::new("/toolchain/rust/library/core/src/lib.rs"))
                .is_none()
        );
    }

    #[test]
    fn configured_ancestor_wins_over_nested_workspace_for_source_identity() {
        let normalizer = pn_with_rules(vec![("/sandbox/checkout", "<WORKSPACE>")])
            .with_base_dirs(&["/sandbox".to_string()]);
        let source = Path::new("/sandbox/checkout/src/lib.rs");

        assert_eq!(
            normalizer.source_path_identity(source).unwrap(),
            b"<BASE_DIR_0>/checkout/src/lib.rs"
        );
        assert_eq!(
            apply_last_match(&normalizer.remap_args(), source.to_str().unwrap()),
            "/kache/base-dir-0/checkout/src/lib.rs"
        );
    }

    #[test]
    fn configured_ancestor_also_wins_depinfo_ownership() {
        let dir = TempDir::new().unwrap();
        let configured = dir.path().join("configured");
        let workspace = configured.join("checkout");
        let source = workspace.join("src/lib.rs");
        std::fs::create_dir_all(source.parent().unwrap()).unwrap();
        std::fs::write(&source, "pub const VALUE: u8 = 1;").unwrap();

        let normalizer = PathNormalizer::from_env(Some(&workspace))
            .with_base_dirs(&[configured.to_string_lossy().into_owned()]);
        let relative = source.strip_prefix(&configured).unwrap().to_string_lossy();
        assert_eq!(
            normalizer.source_path_identity(&source).unwrap(),
            format!("<BASE_DIR_0>/{relative}").as_bytes()
        );

        let roots = normalizer.depinfo_source_roots();
        assert!(!roots.iter().any(|root| {
            root.root == workspace
                && matches!(
                    root.depinfo_sentinel.as_str(),
                    "__kache_cwd__/" | "__kache_workspace__/"
                )
        }));
        let roots = roots
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let target = workspace.join("target");
        let raw = format!("{}/demo.d: {}\n", target.display(), source.display());
        let stored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &raw,
            &target,
            &workspace,
            Some(&workspace),
            &roots,
            crate::link::DepInfoMode::Relativize,
        );
        assert!(
            stored.contains(&format!("__kache_base_dir_0__/{relative}")),
            "{stored}"
        );
        assert!(!stored.contains("__kache_cwd__/"), "{stored}");
        assert!(!stored.contains("__kache_workspace__/"), "{stored}");
    }

    #[cfg(unix)]
    #[test]
    fn configured_lexical_root_is_not_stolen_by_another_roots_alias() {
        let dir = TempDir::new().unwrap();
        let real_path = dir.path().join("z-real");
        let link_path = dir.path().join("a-link");
        std::fs::create_dir_all(real_path.join("src")).unwrap();
        std::os::unix::fs::symlink(&real_path, &link_path).unwrap();

        let link = link_path.to_string_lossy().into_owned();
        let real = real_path.to_string_lossy().into_owned();
        let normalizer = PathNormalizer::empty().with_base_dirs(&[link.clone(), real.clone()]);

        assert_eq!(normalizer.configured_base_dir_count(), 2);
        assert_eq!(
            normalizer.normalize(format!("{link}/src")),
            "<BASE_DIR_0>/src"
        );
        assert_eq!(
            normalizer.normalize(format!("{real}/src")),
            "<BASE_DIR_1>/src"
        );
        assert_eq!(
            normalizer
                .source_path_identity(&link_path.join("src/lib.rs"))
                .unwrap(),
            b"<BASE_DIR_0>/src/lib.rs"
        );
        assert_eq!(
            normalizer
                .source_path_identity(&real_path.join("src/lib.rs"))
                .unwrap(),
            b"<BASE_DIR_1>/src/lib.rs"
        );

        let roots = normalizer.depinfo_source_roots();
        assert!(roots.iter().any(|root| {
            root.root == link_path
                && root.key_sentinel == "<BASE_DIR_0>"
                && root.depinfo_sentinel == "__kache_base_dir_0__/"
                && root.priority == flag_emit_rank("<BASE_DIR_0>")
        }));
        assert!(roots.iter().any(|root| {
            root.root == real_path
                && root.key_sentinel == "<BASE_DIR_1>"
                && root.depinfo_sentinel == "__kache_base_dir_1__/"
                && root.priority == flag_emit_rank("<BASE_DIR_1>")
        }));
        assert!(!roots.iter().any(|root| {
            root.root == real_path
                && (root.key_sentinel != "<BASE_DIR_1>"
                    || root.depinfo_sentinel != "__kache_base_dir_1__/")
        }));
    }

    #[cfg(unix)]
    #[test]
    fn configured_symlink_alias_restores_through_lexical_root_after_retarget() {
        let dir = TempDir::new().unwrap();
        let old_real = dir.path().join("a-very-long-old-real-target");
        let new_real = dir.path().join("new-real-target");
        let link = dir.path().join("x");
        std::fs::create_dir_all(old_real.join("src")).unwrap();
        std::fs::create_dir_all(new_real.join("src")).unwrap();
        std::os::unix::fs::symlink(&old_real, &link).unwrap();
        let configured = link.to_string_lossy().into_owned();

        let producer = PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&configured));
        let producer_roots = producer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let old_canonical = old_real.canonicalize().unwrap();
        let input = format!("out: {}/src/value.rs\n", old_canonical.display());
        let stored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &input,
            Path::new("/unrelated-target"),
            Path::new("/unrelated-cwd"),
            None,
            &producer_roots,
            crate::link::DepInfoMode::Relativize,
        );
        assert!(
            stored.contains("__kache_base_dir_0__/src/value.rs"),
            "{stored}"
        );

        std::fs::remove_file(&link).unwrap();
        std::os::unix::fs::symlink(&new_real, &link).unwrap();
        let consumer = PathNormalizer::empty().with_base_dirs(&[configured]);
        let consumer_roots = consumer
            .depinfo_source_roots()
            .into_iter()
            .map(|root| (root.root, root.depinfo_sentinel, root.priority))
            .collect::<Vec<_>>();
        let restored = crate::link::rewrite_rustc_depinfo_content_with_configured_roots(
            &stored,
            Path::new("/other-target"),
            Path::new("/other-cwd"),
            None,
            &consumer_roots,
            crate::link::DepInfoMode::Expand,
        );
        assert!(restored.contains(&format!("{}/src/value.rs", link.display())));
        assert!(!restored.contains(old_canonical.to_str().unwrap()));
    }

    #[test]
    fn configured_base_dirs_relocate_equivalently_but_stay_distinct() {
        let host_a = TempDir::new().unwrap();
        let host_b = TempDir::new().unwrap();
        let root_a = host_a.path().join("mount");
        let root_b = host_b.path().join("mount");
        std::fs::create_dir_all(&root_a).unwrap();
        std::fs::create_dir_all(&root_b).unwrap();

        let root_a_cfg = root_a.to_string_lossy().into_owned();
        let root_b_cfg = root_b.to_string_lossy().into_owned();
        let a = PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&root_a_cfg));
        let b = PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&root_b_cfg));
        let a_input = format!("{}/pkg/file.rs", canonical_string(&root_a).unwrap());
        let b_input = format!("{}/pkg/file.rs", canonical_string(&root_b).unwrap());
        assert_eq!(a.normalize(&a_input), b.normalize(&b_input));
        assert_eq!(a.normalize(&a_input), "<BASE_DIR_0>/pkg/file.rs");

        let distinct = PathNormalizer::empty().with_base_dirs(&[root_a_cfg, root_b_cfg]);
        assert_ne!(distinct.normalize(&a_input), distinct.normalize(&b_input));
    }

    #[test]
    fn configured_missing_root_still_normalizes_and_emits_auditable_remap() {
        let dir = TempDir::new().unwrap();
        let missing = dir.path().join("not-mounted-here");
        let input = format!("{}/target/out.o", missing.display());
        let missing_cfg = missing.to_string_lossy().into_owned();
        let normalizer = PathNormalizer::empty().with_base_dirs(std::slice::from_ref(&missing_cfg));

        assert_eq!(normalizer.normalize(&input), "<BASE_DIR_0>/target/out.o");
        let expected = format!(
            "--remap-path-prefix={}={}",
            missing.display(),
            configured_base_dir_target(0)
        );
        assert!(normalizer.remap_args().iter().any(|arg| arg == &expected));
    }
}