deps_core/

lockfile.rs

//! Lock file parsing abstractions.
//!
//! Provides generic types and traits for parsing lock files across different
//! package ecosystems (Cargo.lock, package-lock.json, poetry.lock, etc.).
//!
//! Lock files contain resolved dependency versions, allowing instant display
//! without network requests to registries.

use crate::error::{DepsError, Result};
use crate::fs_probe;
use dashmap::DashMap;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::time::{Instant, SystemTime};
use url::Url;

/// Maximum depth to search for workspace root lock file.
const MAX_WORKSPACE_DEPTH: usize = 5;

/// Maximum lock file size [`read_lockfile_content`] reads before parsing.
///
/// Deliberately a separate, larger constant than [`crate::mtime_cache::MAX_CACHED_FILE_BYTES`]
/// — that cap is scoped to small config files (`.cargo/config.toml`, `.npmrc`, typically a
/// few KB), while a lock file records every transitively resolved package across an entire
/// dependency graph, and a large npm monorepo `package-lock.json` can legitimately run well
/// past 8 MiB. 32 MiB matches [`crate::cache`]'s `MAX_RESPONSE_BYTES` order of magnitude —
/// generous for any realistic lock file while still bounding the read against a
/// maliciously large one discovered by an unauthenticated ancestor walk over a cloned
/// repository (CWE-400).
pub const MAX_LOCKFILE_BYTES: u64 = 32 * 1024 * 1024;

/// Reads a lock file's contents, wrapping any I/O failure into a [`DepsError::ParseError`]
/// tagged with the ecosystem's `file_type` label and the file's path.
///
/// Every `LockFileProvider::parse_lockfile` implementation reads its lock file the same
/// way; this shares that boilerplate and keeps the error message format consistent
/// across ecosystems.
///
/// Bounded by [`MAX_LOCKFILE_BYTES`] via [`fs_probe::read_to_string_capped`] — a lock file
/// is discovered by an unauthenticated ancestor walk ([`locate_lockfile_for_manifest`]) over
/// a possibly hostile cloned repository, so nothing here may assume it is reasonably sized
/// or a regular file before reading it in full (CWE-400). The whole stat-then-read sequence
/// runs as one unit on the blocking-thread pool via [`tokio::task::spawn_blocking`], not on
/// the calling tokio worker thread: both steps are synchronous I/O with no `.await` of their
/// own, and every `LockFileProvider::parse_lockfile` call site sits on the LSP request path,
/// where a worker thread blocked on a `stat` or an 8+ MiB read — or indefinitely, on a FIFO —
/// would violate the project's non-blocking-handler rule (#963).
///
/// # Errors
///
/// Returns [`DepsError::ParseError`] if the file cannot be read (e.g. missing, not a
/// regular file, unreadable, invalid UTF-8), exceeds [`MAX_LOCKFILE_BYTES`], or the
/// blocking read task panicked.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::read_lockfile_content;
/// use std::path::Path;
///
/// # async fn example() -> deps_core::error::Result<()> {
/// let content = read_lockfile_content(Path::new("Cargo.lock"), "Cargo.lock").await?;
/// println!("{} bytes read", content.len());
/// # Ok(())
/// # }
/// ```
#[tracing::instrument(skip_all, fields(path = %path.display(), file_type = %file_type), level = "debug")]
pub async fn read_lockfile_content(path: &Path, file_type: &str) -> Result<String> {
    let to_parse_error = |e: std::io::Error| {
        DepsError::parse_error(format!("{file_type} at {}", path.display()), &e)
    };
    let oversized_error = || {
        to_parse_error(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("exceeds {MAX_LOCKFILE_BYTES} byte size cap"),
        ))
    };

    // Entered inside the closure below so the `path`/`file_type` fields this function's
    // `#[tracing::instrument]` attaches to its span still show up on events logged from the
    // blocking pool — a span is not implicitly active on whatever thread `spawn_blocking`
    // happens to run its closure on.
    let span = tracing::Span::current();
    let path_buf = path.to_path_buf();
    let read_result = tokio::task::spawn_blocking(move || {
        let _entered = span.enter();
        // Cheap `stat` pre-filter (mirrors `MtimeFileCache::get_or_parse`): rejects a
        // non-regular file (can block indefinitely) and an oversized file before opening. The
        // capped read below still enforces the size bound regardless, closing the TOCTOU gap
        // (CWE-367) a stat-only check would leave open.
        if let Ok(metadata) = fs_probe::metadata(&path_buf) {
            if !metadata.is_file() {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "not a regular file",
                ));
            }
            if metadata.len() > MAX_LOCKFILE_BYTES {
                tracing::warn!(
                    path = %path_buf.display(),
                    len = metadata.len(),
                    cap = MAX_LOCKFILE_BYTES,
                    "lock file exceeds size cap; not reading"
                );
                return Err(std::io::Error::new(
                    std::io::ErrorKind::InvalidData,
                    format!("exceeds {MAX_LOCKFILE_BYTES} byte size cap"),
                ));
            }
        }

        fs_probe::read_to_string_capped(&path_buf, MAX_LOCKFILE_BYTES)
    })
    .await
    .map_err(|e| to_parse_error(std::io::Error::other(e)))?;

    match read_result.map_err(to_parse_error)? {
        Some(content) => Ok(content),
        None => {
            tracing::warn!(
                path = %path.display(),
                cap = MAX_LOCKFILE_BYTES,
                "lock file exceeds size cap during read; not reading"
            );
            Err(oversized_error())
        }
    }
}

/// Reads a lock file via [`read_lockfile_content`] and runs `parse` on the blocking-thread
/// pool, returning the parsed result.
///
/// Every `LockFileProvider::parse_lockfile` implementation reads its lock file's content and
/// then parses it; this shares that second half of the boilerplate too. The parse step is
/// CPU-bound work over content bounded by the same [`MAX_LOCKFILE_BYTES`] cap as the read
/// (a `Cargo.lock`/`package-lock.json`/... TOML, JSON, or YAML document up to 32 MiB), so —
/// like the read itself — it must never run on the calling tokio worker thread: every
/// `LockFileProvider::parse_lockfile` call site sits on the LSP request path, where a worker
/// thread blocked on parsing a multi-megabyte document would violate the project's
/// non-blocking-handler rule.
///
/// # Errors
///
/// Returns whatever [`read_lockfile_content`] returns for a read failure, whatever `parse`
/// itself returns for a malformed document, or a [`DepsError::ParseError`] if the blocking
/// parse task panics or is cancelled.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::{read_and_parse_lockfile, ResolvedPackages};
/// use std::path::Path;
///
/// # async fn example() -> deps_core::error::Result<()> {
/// let packages: ResolvedPackages = read_and_parse_lockfile(
///     Path::new("Cargo.lock"),
///     "Cargo.lock",
///     |content| Ok(ResolvedPackages::new()), // real parsers inspect `content`
/// )
/// .await?;
/// # Ok(())
/// # }
/// ```
#[tracing::instrument(skip_all, fields(path = %path.display(), file_type = %file_type), level = "debug")]
pub async fn read_and_parse_lockfile<T, F>(path: &Path, file_type: &str, parse: F) -> Result<T>
where
    F: FnOnce(String) -> Result<T> + Send + 'static,
    T: Send + 'static,
{
    let content = read_lockfile_content(path, file_type).await?;

    tokio::task::spawn_blocking(move || parse(content))
        .await
        .map_err(|e| DepsError::parse_error(format!("{file_type} at {}", path.display()), &e))?
}

/// Resolves a manifest URI to an absolute local filesystem path, rejecting a non-`file:`
/// scheme, a relative path, or a non-local host.
///
/// `url::Url::to_file_path` on its own already refuses a non-empty, non-`localhost` host (it
/// checks cannot-be-a-base and host) — but it does **not** check the URI's scheme at all, so a
/// non-`file:` URI shaped like a real path (e.g. `untitled:/etc/passwd`, VS Code's
/// untitled-buffer scheme) would otherwise silently resolve to a real local path (#1084,
/// confirmed empirically: `untitled:/etc/x`, `git:/etc/x`, `vscode-remote:/etc/x` all resolve
/// via `to_file_path`). The explicit host check here is kept as defense-in-depth alongside the
/// scheme check, rather than relying solely on `to_file_path`'s own internal host validation,
/// so both guards are visible at this one call site. The general-purpose guard for resolving
/// any client-supplied manifest/document URI to a real filesystem path before touching disk —
/// not limited to lock file discovery despite living in this module. Shared by
/// [`locate_lockfile_for_manifest`] and every ecosystem-local lock file locator that needs the
/// same manifest-path resolution, as well as non-lock-file call sites across `deps-cargo`,
/// `deps-nuget`, `deps-pypi`, `deps-npm`,
/// `deps-gradle`, and `deps-lsp` (workspace-root and config discovery, document links,
/// cold-start document loading, and watched-file-change handling) that resolve the same kind
/// of URI for the same reason (#1090) — so the guard is defined once, not re-derived per call
/// site.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::resolve_manifest_file_path;
/// use url::Url;
///
/// // `no_run`: `/path/to/Cargo.toml` is not absolute on Windows (no drive prefix), so
/// // `Url::from_file_path` would return `Err` there — same reason the example right
/// // below (`locate_lockfile_for_manifest`'s) is also `no_run`.
/// let file_uri = Url::from_file_path("/path/to/Cargo.toml").unwrap();
/// assert!(resolve_manifest_file_path(&file_uri).is_some());
///
/// let non_file_uri: Url = "untitled:/path/to/Cargo.toml".parse().unwrap();
/// assert!(resolve_manifest_file_path(&non_file_uri).is_none());
/// ```
#[must_use]
pub fn resolve_manifest_file_path(manifest_uri: &Url) -> Option<PathBuf> {
    if !manifest_uri.scheme().eq_ignore_ascii_case("file") {
        return None;
    }
    if let Some(host) = manifest_uri.host_str()
        && !host.is_empty()
        && !host.eq_ignore_ascii_case("localhost")
    {
        return None;
    }
    let manifest_path = manifest_uri.to_file_path().ok()?;
    manifest_path.is_absolute().then_some(manifest_path)
}

/// Generic lock file locator.
///
/// Searches for lock files in the following order:
/// 1. Same directory as the manifest
/// 2. Parent directories (up to MAX_WORKSPACE_DEPTH levels) for workspace root
///
/// Each candidate is checked with [`fs_probe::is_file`], not a plain existence check — a
/// FIFO or socket happening to sit at a lock file's conventional name must never be
/// returned as "found", since [`read_lockfile_content`] opening one would block
/// indefinitely.
///
/// This function is ecosystem-agnostic and works with any lock file name.
///
/// # Arguments
///
/// * `manifest_uri` - URI of the manifest file
/// * `lockfile_names` - List of possible lock file names to search for, checked in the given
///   order within each directory before moving up to its parent. A caller with more than one
///   valid name for the same manifest should pass all of them in one call rather than
///   searching separately — that makes the *nearest* directory win regardless of which name
///   matches there, instead of an ancestor's unrelated file shadowing a closer, more specific
///   one.
///
/// # Returns
///
/// Path to the first found lock file, or None if not found.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::locate_lockfile_for_manifest;
/// use url::Url;
///
/// let manifest_uri = Url::from_file_path("/path/to/Cargo.toml").unwrap();
/// let lockfile_names = &["Cargo.lock"];
///
/// if let Some(path) = locate_lockfile_for_manifest(&manifest_uri, lockfile_names) {
///     println!("Found lock file at: {}", path.display());
/// }
/// ```
pub fn locate_lockfile_for_manifest(
    manifest_uri: &Url,
    lockfile_names: &[&str],
) -> Option<PathBuf> {
    locate_lockfile_for_manifest_with_max_depth(manifest_uri, lockfile_names, MAX_WORKSPACE_DEPTH)
}

/// Same as [`locate_lockfile_for_manifest`], but with an explicit cap on how many ancestor
/// directories are searched after the manifest's own directory.
///
/// Most ecosystems share a lock file across a workspace, so they should keep using
/// [`locate_lockfile_for_manifest`] (which searches up to `MAX_WORKSPACE_DEPTH` ancestors).
/// An ecosystem whose lock file is genuinely per-project (e.g. NuGet's
/// `packages.lock.json`, one per `.csproj`) should pass `max_ancestor_depth: 0` here instead,
/// so an unrelated ancestor's lock file is never misattributed to a manifest that has none of
/// its own (#1357).
///
/// # Arguments
///
/// * `manifest_uri` - URI of the manifest file
/// * `lockfile_names` - List of possible lock file names to search for, checked in the given
///   order within each directory before moving up to its parent.
/// * `max_ancestor_depth` - How many parent directories to search after the manifest's own
///   directory. `0` restricts the search to the manifest's own directory only.
///
/// # Returns
///
/// Path to the first found lock file, or None if not found.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::locate_lockfile_for_manifest_with_max_depth;
/// use url::Url;
///
/// let manifest_uri = Url::from_file_path("/path/to/project/project.csproj").unwrap();
/// let lockfile_names = &["packages.lock.json"];
///
/// // NuGet lock files are per-project, so restrict the search to the manifest's own
/// // directory — an unrelated ancestor project's lock file must never be picked up.
/// if let Some(path) =
///     locate_lockfile_for_manifest_with_max_depth(&manifest_uri, lockfile_names, 0)
/// {
///     println!("Found lock file at: {}", path.display());
/// }
/// ```
pub fn locate_lockfile_for_manifest_with_max_depth(
    manifest_uri: &Url,
    lockfile_names: &[&str],
    max_ancestor_depth: usize,
) -> Option<PathBuf> {
    let manifest_path = resolve_manifest_file_path(manifest_uri)?;
    let manifest_dir = manifest_path.parent()?;

    let mut lock_path = manifest_dir.to_path_buf();

    for &name in lockfile_names {
        lock_path.push(name);
        if fs_probe::is_file(&lock_path) {
            tracing::debug!("Found {} at: {}", name, lock_path.display());
            return Some(lock_path);
        }
        lock_path.pop();
    }

    // Search up the directory tree for workspace root
    let Some(mut current_dir) = manifest_dir.parent() else {
        tracing::debug!("No lock file found for: {:?}", manifest_uri);
        return None;
    };

    for depth in 0..max_ancestor_depth {
        lock_path.clear();
        lock_path.push(current_dir);

        for &name in lockfile_names {
            lock_path.push(name);
            if fs_probe::is_file(&lock_path) {
                tracing::debug!(
                    "Found workspace {} at depth {}: {}",
                    name,
                    depth + 1,
                    lock_path.display()
                );
                return Some(lock_path);
            }
            lock_path.pop();
        }

        match current_dir.parent() {
            Some(parent) => current_dir = parent,
            None => break,
        }
    }

    tracing::debug!("No lock file found for: {:?}", manifest_uri);
    None
}

/// Resolved package information from a lock file.
///
/// Contains the exact version and source information for a dependency
/// as resolved by the package manager.
#[non_exhaustive]
#[derive(Clone, PartialEq, Eq)]
pub struct ResolvedPackage {
    /// Package name
    pub name: String,
    /// Resolved version (exact version from lock file)
    pub version: String,
    /// Source information (registry URL, git commit, path)
    pub source: ResolvedSource,
    /// Dependencies of this package (for dependency tree analysis)
    pub dependencies: Vec<String>,
}

impl std::fmt::Debug for ResolvedPackage {
    /// Manual, not derived: `name` and `dependencies` are raw lock-file package names (the
    /// weaker #1217 name shape), and `source`'s own `Debug` (see [`ResolvedSource`]) redacts
    /// the credential-capable URL its `Registry`/`Git` variants carry (#1237).
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ResolvedPackage")
            .field(
                "name",
                &crate::net_policy::redact_declaration_key(&self.name),
            )
            .field("version", &self.version)
            .field("source", &self.source)
            .field(
                "dependencies",
                &self
                    .dependencies
                    .iter()
                    .map(|name| crate::net_policy::redact_declaration_key(name))
                    .collect::<Vec<_>>(),
            )
            .finish()
    }
}

impl ResolvedPackage {
    /// Constructs a `ResolvedPackage` from its three required fields, with
    /// [`Self::dependencies`] left empty — chain [`Self::with_dependencies`] to attach them.
    ///
    /// Needed because [`Self`] is `#[non_exhaustive]`: a struct literal only works inside
    /// this crate, so every other crate must go through this constructor instead.
    ///
    /// # Examples
    ///
    /// ```
    /// use deps_core::lockfile::{ResolvedPackage, ResolvedSource};
    ///
    /// let package = ResolvedPackage::new(
    ///     "serde".to_string(),
    ///     "1.0.195".to_string(),
    ///     ResolvedSource::Registry {
    ///         url: "https://github.com/rust-lang/crates.io-index".into(),
    ///         checksum: "abc123".into(),
    ///     },
    /// );
    /// assert!(package.dependencies.is_empty());
    /// ```
    #[must_use]
    pub fn new(name: String, version: String, source: ResolvedSource) -> Self {
        Self {
            name,
            version,
            source,
            dependencies: Vec::new(),
        }
    }

    /// Attaches this package's own dependencies. See [`Self::dependencies`].
    #[must_use]
    pub fn with_dependencies(mut self, dependencies: Vec<String>) -> Self {
        self.dependencies = dependencies;
        self
    }
}

/// Source of a resolved dependency.
///
/// Indicates where the package was downloaded from or how it was resolved.
#[non_exhaustive]
#[derive(Clone, PartialEq, Eq)]
pub enum ResolvedSource {
    /// From a registry with optional checksum
    Registry {
        /// Registry URL
        url: String,
        /// Checksum/integrity hash
        checksum: String,
    },
    /// From git with commit hash
    Git {
        /// Git repository URL
        url: String,
        /// Commit SHA or tag
        rev: String,
    },
    /// From local file system
    Path {
        /// Relative or absolute path
        path: String,
    },
}

impl std::fmt::Debug for ResolvedSource {
    /// Manual, not derived: `Registry`/`Git`'s `url` is copied verbatim from the lock file
    /// (e.g. Cargo's `git+https://user:token@host/repo`, npm's `resolved`) and can carry a
    /// credential; `Path`'s `path` is also redacted defensively, since it is the catch-all a
    /// caller may put an unrecognized URL scheme into (e.g. Cargo's `unknown-scheme+https://`
    /// sources — `sparse+` itself is classified as `Registry` since #1320) rather than a
    /// filesystem path (CWE-532, #1237).
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Registry { url, checksum } => f
                .debug_struct("Registry")
                .field("url", &crate::net_policy::RedactedUrl::new(url))
                .field("checksum", checksum)
                .finish(),
            Self::Git { url, rev } => f
                .debug_struct("Git")
                .field("url", &crate::net_policy::RedactedUrl::new(url))
                .field("rev", rev)
                .finish(),
            Self::Path { path } => f
                .debug_struct("Path")
                .field("path", &crate::net_policy::redact_declaration_key(path))
                .finish(),
        }
    }
}

/// Collection of resolved packages from a lock file.
///
/// Supports multiple versions per package name, returning the highest
/// semver version through public API methods.
///
/// # Examples
///
/// ```
/// use deps_core::lockfile::{ResolvedPackages, ResolvedPackage, ResolvedSource};
///
/// let mut packages = ResolvedPackages::new();
/// packages.insert(
///     ResolvedPackage::new(
///         "serde".into(),
///         "1.0.195".into(),
///         ResolvedSource::Registry {
///             url: "https://github.com/rust-lang/crates.io-index".into(),
///             checksum: "abc123".into(),
///         },
///     )
///     .with_dependencies(vec!["serde_derive".into()]),
/// );
///
/// assert_eq!(packages.version("serde"), Some("1.0.195"));
/// assert_eq!(packages.len(), 1);
/// ```
#[derive(Default, Clone)]
pub struct ResolvedPackages {
    packages: HashMap<String, Vec<ResolvedPackage>>,
}

impl std::fmt::Debug for ResolvedPackages {
    /// Manual, not derived: the `HashMap` key is the same lock-file package name
    /// [`ResolvedPackage::name`] carries, so a derived impl would print it twice — once raw
    /// (as the key) and once through whatever redaction `ResolvedPackage`'s own `Debug` applies
    /// (#1319).
    ///
    /// Renders through [`std::fmt::Formatter::debug_map`] rather than collecting redacted keys
    /// into a real `HashMap` first: two distinct names that happen to redact to the same marker
    /// (e.g. two different credentials against the same host) would otherwise collide and
    /// silently drop one package from the output.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        struct RedactedMap<'a>(&'a HashMap<String, Vec<ResolvedPackage>>);

        impl std::fmt::Debug for RedactedMap<'_> {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.debug_map()
                    .entries(self.0.iter().map(|(name, versions)| {
                        (crate::net_policy::redact_declaration_key(name), versions)
                    }))
                    .finish()
            }
        }

        f.debug_struct("ResolvedPackages")
            .field("packages", &RedactedMap(&self.packages))
            .finish()
    }
}

/// Orders two version strings, preferring a valid semver parse over a non-parseable one and
/// falling back to a lexicographic compare when both (or neither) parse.
///
/// Shared by [`best_package`] and the per-occurrence candidate selection in
/// [`crate::lsp_helpers::resolve_in_use_version`] (issue #649) so a lock file entry with a
/// non-semver version string is never ordered by two diverging policies depending on which
/// caller is asking.
pub(crate) fn compare_lockfile_versions(a: &str, b: &str) -> std::cmp::Ordering {
    match (semver::Version::parse(a), semver::Version::parse(b)) {
        (Ok(va), Ok(vb)) => va.cmp(&vb),
        (Ok(_), Err(_)) => std::cmp::Ordering::Greater,
        (Err(_), Ok(_)) => std::cmp::Ordering::Less,
        (Err(_), Err(_)) => a.cmp(b),
    }
}

/// Returns the package with the highest semver version from a slice.
fn best_package(packages: &[ResolvedPackage]) -> Option<&ResolvedPackage> {
    packages
        .iter()
        .max_by(|a, b| compare_lockfile_versions(&a.version, &b.version))
}

impl ResolvedPackages {
    /// Creates a new empty collection.
    pub fn new() -> Self {
        Self {
            packages: HashMap::new(),
        }
    }

    /// Inserts a resolved package, storing all versions per name.
    pub fn insert(&mut self, package: ResolvedPackage) {
        self.packages
            .entry(package.name.clone())
            .or_default()
            .push(package);
    }

    /// Gets the resolved package with the highest semver version.
    pub fn get(&self, name: &str) -> Option<&ResolvedPackage> {
        self.packages.get(name).and_then(|v| best_package(v))
    }

    /// Gets the highest resolved version string for a package.
    pub fn version(&self, name: &str) -> Option<&str> {
        self.get(name).map(|p| p.version.as_str())
    }

    /// Returns all stored versions for a package.
    pub fn all(&self, name: &str) -> Option<&[ResolvedPackage]> {
        self.packages.get(name).map(|v| v.as_slice())
    }

    /// Returns an iterator yielding every stored version for each unique package name,
    /// unlike [`Self::iter`] which collapses each name down to `best_package`'s single
    /// pick.
    ///
    /// The building block for per-occurrence lock-file resolution (issue #649): a caller
    /// disambiguating two manifest occurrences of the same resolved package name (e.g. a
    /// Cargo `package = "..."` rename pinning an older major alongside a plain dependency
    /// on the current major) needs every retained version for that name, not just the one
    /// [`Self::iter`]/[`Self::into_map`] would collapse it to.
    pub fn iter_all(&self) -> impl Iterator<Item = (&String, &[ResolvedPackage])> {
        self.packages
            .iter()
            .map(|(name, versions)| (name, versions.as_slice()))
    }

    /// Returns the number of unique package names.
    pub fn len(&self) -> usize {
        self.packages.len()
    }

    /// Returns true if there are no resolved packages.
    pub fn is_empty(&self) -> bool {
        self.packages.is_empty()
    }

    /// Returns an iterator yielding the best version per unique package name.
    pub fn iter(&self) -> impl Iterator<Item = (&String, &ResolvedPackage)> {
        self.packages.keys().filter_map(|name| {
            self.packages
                .get(name)
                .and_then(|v| best_package(v).map(|p| (name, p)))
        })
    }

    /// Converts into a HashMap with the best version per package name.
    pub fn into_map(self) -> HashMap<String, ResolvedPackage> {
        self.packages
            .into_iter()
            .filter_map(|(name, versions)| best_package(&versions).cloned().map(|p| (name, p)))
            .collect()
    }
}

/// Lock file provider trait for ecosystem-specific implementations.
///
/// Implementations parse lock files for a specific package ecosystem
/// (Cargo.lock, package-lock.json, etc.) and extract resolved versions.
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::{LockFileProvider, ResolvedPackages};
/// use std::path::{Path, PathBuf};
/// use url::Url;
///
/// struct MyLockParser;
///
/// impl LockFileProvider for MyLockParser {
///     fn locate_lockfile(&self, manifest_uri: &Url) -> Option<PathBuf> {
///         let manifest_path = manifest_uri.to_file_path().ok()?;
///         let lock_path = manifest_path.with_file_name("my.lock");
///         lock_path.exists().then_some(lock_path)
///     }
///
///     fn parse_lockfile<'a>(&'a self, lockfile_path: &'a Path) -> std::pin::Pin<Box<dyn std::future::Future<Output = deps_core::error::Result<ResolvedPackages>> + Send + 'a>> {
///         Box::pin(async move {
///             // Parse lock file format and extract packages
///             Ok(ResolvedPackages::new())
///         })
///     }
/// }
/// ```
pub trait LockFileProvider: Send + Sync {
    /// Locates the lock file for a given manifest URI.
    ///
    /// Returns `None` if:
    /// - Lock file doesn't exist
    /// - Manifest path cannot be determined from URI
    /// - Workspace root search fails
    ///
    /// # Arguments
    ///
    /// * `manifest_uri` - URI of the manifest file (Cargo.toml, package.json, etc.)
    ///
    /// # Returns
    ///
    /// Path to lock file if found
    fn locate_lockfile(&self, manifest_uri: &Url) -> Option<PathBuf>;

    /// Parses a lock file and extracts resolved packages.
    ///
    /// # Arguments
    ///
    /// * `lockfile_path` - Path to the lock file
    ///
    /// # Returns
    ///
    /// ResolvedPackages on success, error if parse fails
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - File cannot be read
    /// - File format is invalid
    /// - Required fields are missing
    fn parse_lockfile<'a>(
        &'a self,
        lockfile_path: &'a Path,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<ResolvedPackages>> + Send + 'a>>;
}

/// Upper bound on a [`LockFileCache`]'s entry count.
///
/// Matches [`crate::mtime_cache::DEFAULT_MAX_CACHED_FILES`] — the same generous bound for
/// any realistic workspace's set of *distinct* lock files. Without a cap, a long-running
/// server session that opens many workspaces over time (or one pointed at a monorepo with
/// many independently-locked sub-projects) would grow this cache unboundedly, since entries
/// previously survived even a `textDocument/didClose` (#962).
///
/// Bounds this cache's worst-case retained content at `DEFAULT_MAX_CACHED_LOCKFILES *
/// MAX_LOCKFILE_BYTES` (256 * 32 MiB = 8 GiB of raw lock file content, before accounting for
/// parsed [`ResolvedPackages`] overhead) — generous headroom rather than a tight budget,
/// since a byte-accounted eviction policy (like [`crate::cache::HttpCache`]'s) is more
/// precision than this entry-count-keyed cache needs.
pub const DEFAULT_MAX_CACHED_LOCKFILES: usize = 256;

/// Cached lock file entry with staleness detection.
struct CachedLockFile {
    packages: ResolvedPackages,
    modified_at: SystemTime,
    /// When this entry was last parsed *or* served from a cache hit — the recency key
    /// [`LockFileCache::evict_oldest`] evicts by once the cache is at capacity. Refreshed on
    /// every access (not only on (re)parse), so eviction is genuinely LRU rather than
    /// FIFO-by-parse-time — otherwise a stable, frequently-read lock file would look oldest
    /// and get evicted first, while one that keeps changing (and reparsing) would never age
    /// out.
    parsed_at: Instant,
}

/// Cache for parsed lock files with automatic staleness detection.
///
/// Caches parsed lock file contents and checks file modification time
/// to avoid re-parsing unchanged files. Thread-safe for concurrent access.
///
/// Bounded by a capacity ([`DEFAULT_MAX_CACHED_LOCKFILES`] by default, via [`Self::new`]; a
/// custom bound via [`Self::with_capacity`]): once full, inserting a new key evicts the
/// least-recently-used entry first, keyed by `CachedLockFile::parsed_at`, which is
/// refreshed on every cache hit as well as every (re)parse (#962).
///
/// # Examples
///
/// ```no_run
/// use deps_core::lockfile::LockFileCache;
/// use std::path::Path;
///
/// # async fn example() -> deps_core::error::Result<()> {
/// let cache = LockFileCache::new();
/// // First call parses the file
/// // Second call returns cached result if file hasn't changed
/// # Ok(())
/// # }
/// ```
pub struct LockFileCache {
    entries: DashMap<PathBuf, CachedLockFile>,
    capacity: usize,
}

impl std::fmt::Debug for LockFileCache {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LockFileCache")
            .field("capacity", &self.capacity)
            .field("len", &self.entries.len())
            .finish_non_exhaustive()
    }
}

impl LockFileCache {
    /// Creates a new empty lock file cache, capped at [`DEFAULT_MAX_CACHED_LOCKFILES`]
    /// entries.
    #[must_use]
    pub fn new() -> Self {
        Self::with_capacity(DEFAULT_MAX_CACHED_LOCKFILES)
    }

    /// Creates a new empty lock file cache, capped at `capacity` entries.
    ///
    /// # Examples
    ///
    /// ```
    /// use deps_core::lockfile::LockFileCache;
    ///
    /// let cache = LockFileCache::with_capacity(64);
    /// assert!(cache.is_empty());
    /// ```
    #[must_use]
    pub fn with_capacity(capacity: usize) -> Self {
        Self {
            entries: DashMap::new(),
            capacity,
        }
    }

    /// Evicts the least-recently-used entry, making room for one new insert.
    ///
    /// A full scan of `entries` by [`CachedLockFile::parsed_at`] — acceptable at this
    /// cache's scale (bounded by `capacity`, [`DEFAULT_MAX_CACHED_LOCKFILES`] by default),
    /// unlike [`crate::osv`]'s cache, which is sized an order of magnitude larger and batches
    /// its eviction accordingly. Logs at `warn` when eviction actually runs, mirroring
    /// [`crate::mtime_cache::MtimeFileCache`]'s own at-capacity warning.
    fn evict_oldest(&self) {
        let oldest = self
            .entries
            .iter()
            .min_by_key(|entry| entry.parsed_at)
            .map(|entry| entry.key().clone());
        if let Some(key) = oldest {
            tracing::warn!(
                path = %key.display(),
                capacity = self.capacity,
                "lock file cache capacity reached; evicting least-recently-used entry"
            );
            self.entries.remove(&key);
        }
    }

    /// Gets parsed packages from cache or parses the lock file.
    ///
    /// Checks file modification time to detect changes. If the file
    /// has been modified since last parse, re-parses it. Otherwise,
    /// returns the cached result.
    ///
    /// # Arguments
    ///
    /// * `provider` - Lock file provider implementation
    /// * `lockfile_path` - Path to the lock file
    ///
    /// # Returns
    ///
    /// Resolved packages on success
    ///
    /// # Errors
    ///
    /// Returns error if file cannot be read or parsed
    pub async fn get_or_parse(
        &self,
        provider: &dyn LockFileProvider,
        lockfile_path: &Path,
    ) -> Result<ResolvedPackages> {
        // Extract owned data from the cache entry before awaiting: the DashMap shard
        // `Ref` returned by `entries.get` must not be held across `.await`, or a
        // concurrent access to the same key blocks for the duration (#350, same hazard
        // class as #333).
        let cached = self
            .entries
            .get(lockfile_path)
            .map(|entry| (entry.modified_at, entry.packages.clone()));

        if let Some((cached_modified_at, cached_packages)) = cached
            && let Ok(metadata) = tokio::fs::metadata(lockfile_path).await
            && let Ok(mtime) = metadata.modified()
            && mtime <= cached_modified_at
        {
            tracing::debug!("Lock file cache hit: {}", lockfile_path.display());
            // Refresh the recency marker on a hit too, not only on (re)parse: otherwise
            // eviction is FIFO-by-parse-time rather than LRU, evicting a stable,
            // frequently-read lock file before one that keeps changing and reparsing.
            if let Some(mut entry) = self.entries.get_mut(lockfile_path) {
                entry.parsed_at = Instant::now();
            }
            return Ok(cached_packages);
        }

        // Stat *before* parsing and use that pre-parse mtime as the cache key's freshness
        // marker: stat'ing after would let a concurrent rewrite mid-parse store content from
        // the old version under the new version's mtime, looking fresh when stale (#359).
        tracing::debug!("Lock file cache miss: {}", lockfile_path.display());
        let metadata = tokio::fs::metadata(lockfile_path).await?;
        let modified_at = metadata.modified()?;

        let packages = provider.parse_lockfile(lockfile_path).await?;

        if !self.entries.contains_key(lockfile_path) && self.entries.len() >= self.capacity {
            self.evict_oldest();
        }
        self.entries.insert(
            lockfile_path.to_path_buf(),
            CachedLockFile {
                packages: packages.clone(),
                modified_at,
                parsed_at: Instant::now(),
            },
        );

        Ok(packages)
    }

    /// Invalidates cached entry for a lock file.
    ///
    /// Forces next access to re-parse the file. Use when you know
    /// the file has changed but modification time might not reflect it.
    pub fn invalidate(&self, lockfile_path: &Path) {
        self.entries.remove(lockfile_path);
    }

    /// Returns the number of cached lock files.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Returns true if the cache is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

impl Default for LockFileCache {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Builds a URI whose path component is `manifest_path`'s real, absolute path, with the
    /// `file://` prefix `Url::from_file_path` would produce replaced by `prefix` (e.g.
    /// `"untitled:"` or `"file://attacker.example"`).
    ///
    /// Building this via `format!("{prefix}{}", manifest_path.display())` would panic on
    /// Windows: `Path::display()` there uses `\` separators and an unescaped drive letter,
    /// neither of which is a legal URI path character, so `.parse::<Url>()` fails. Routing
    /// through `Url::from_file_path` first reuses its own drive-letter/separator/percent-
    /// encoding handling, so the resulting string parses on every platform.
    fn non_file_uri(prefix: &str, manifest_path: &std::path::Path) -> Url {
        let file_uri = Url::from_file_path(manifest_path).unwrap();
        let path_part = file_uri.as_str().strip_prefix("file://").unwrap();
        format!("{prefix}{path_part}").parse().unwrap()
    }

    #[tokio::test]
    async fn test_read_lockfile_content_success() {
        // Held per `fs_probe::snapshot_guard`'s doc: `read_lockfile_content` transitively
        // touches fs_probe, and this test runs in the same binary as other modules' (e.g.
        // `mtime_cache`'s) diffing tests.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&lock_path, "version = 4").unwrap();

        let content = read_lockfile_content(&lock_path, "Cargo.lock")
            .await
            .unwrap();

        assert_eq!(content, "version = 4");
    }

    /// An oversized lock file must be rejected by the capped read rather than read into
    /// memory in full (CWE-400) — `read_lockfile_content` previously had no size gate at
    /// all (#607). Uses a sparse file (`set_len`, all-zero bytes, valid UTF-8) so the test
    /// does not need to write `MAX_LOCKFILE_BYTES` of real content to disk — `unwrap_err()`
    /// panics outright if the cap is not actually applied, since a sparse file's all-NUL
    /// content is otherwise perfectly valid `String` content for the success path to return.
    #[tokio::test]
    async fn test_read_lockfile_content_rejects_oversized_file() {
        // See the comment in `test_read_lockfile_content_success` on why this guard is
        // needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");
        let file = std::fs::File::create(&lock_path).unwrap();
        file.set_len(MAX_LOCKFILE_BYTES + 1).unwrap();

        let err = read_lockfile_content(&lock_path, "Cargo.lock")
            .await
            .unwrap_err();

        match err {
            DepsError::ParseError { file_type, .. } => {
                assert_eq!(file_type, format!("Cargo.lock at {}", lock_path.display()));
            }
            other => panic!("Expected ParseError, got: {other:?}"),
        }
    }

    /// A non-regular file (a directory here, portable across platforms unlike a FIFO) at
    /// the lock file path must be rejected by the `is_file` stat pre-filter, not handed to
    /// `File::open`/`read_to_string_capped` — the same class of hazard `fs_probe::is_file`'s
    /// own doc warns about (a FIFO would block the read indefinitely).
    #[tokio::test]
    async fn test_read_lockfile_content_rejects_non_regular_file() {
        // See the comment in `test_read_lockfile_content_success` on why this guard is
        // needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::create_dir(&lock_path).unwrap();

        let err = read_lockfile_content(&lock_path, "Cargo.lock")
            .await
            .unwrap_err();

        match err {
            DepsError::ParseError { file_type, .. } => {
                assert_eq!(file_type, format!("Cargo.lock at {}", lock_path.display()));
            }
            other => panic!("Expected ParseError, got: {other:?}"),
        }
    }

    #[tokio::test]
    async fn test_read_lockfile_content_missing_file_wraps_error() {
        // See the comment in `test_read_lockfile_content_success` on why this guard is
        // needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");

        let err = read_lockfile_content(&lock_path, "Cargo.lock")
            .await
            .unwrap_err();

        match err {
            DepsError::ParseError { file_type, .. } => {
                assert_eq!(file_type, format!("Cargo.lock at {}", lock_path.display()));
            }
            other => panic!("Expected ParseError, got: {other:?}"),
        }
    }

    /// The `spawn_blocking` `JoinError`→`DepsError::ParseError` mapping is issue #723's core
    /// concern (a panicking/blocking parse must not silently misbehave or unwind the caller),
    /// but had zero executable coverage — only the `no_run` doctest, which never runs. A
    /// panicking `parse` closure must surface as `Err(DepsError::ParseError)`, labeled the
    /// same way as every other `read_and_parse_lockfile` failure (`"{file_type} at {path}"`),
    /// with the panic message preserved in `source` (tokio's `JoinError: Display` carries it).
    #[tokio::test]
    async fn test_read_and_parse_lockfile_panic_in_parse_becomes_parse_error() {
        // See the comment in `test_read_lockfile_content_success` on why this guard is
        // needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&lock_path, "version = 4").unwrap();

        let err = read_and_parse_lockfile(&lock_path, "Cargo.lock", |_content| -> Result<()> {
            panic!("boom")
        })
        .await
        .unwrap_err();

        match err {
            DepsError::ParseError { file_type, source } => {
                assert_eq!(file_type, format!("Cargo.lock at {}", lock_path.display()));
                assert!(
                    source.to_string().contains("boom"),
                    "panic message should be preserved in the error source, got: {source}"
                );
            }
            other => panic!("Expected ParseError, got: {other:?}"),
        }
    }

    /// Proves `parse` actually runs off the calling (async) thread via `spawn_blocking`, not
    /// merely that the return type happens to line up — the whole point of the fix is that
    /// CPU-bound parsing no longer executes on the tokio worker driving the LSP request.
    #[tokio::test]
    async fn test_read_and_parse_lockfile_runs_parse_off_calling_thread() {
        // See the comment in `test_read_lockfile_content_success` on why this guard is
        // needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&lock_path, "version = 4").unwrap();

        let calling_thread = std::thread::current().id();

        let content = read_and_parse_lockfile(&lock_path, "Cargo.lock", move |content| {
            assert_ne!(
                std::thread::current().id(),
                calling_thread,
                "parse must run on the blocking pool, not the calling thread"
            );
            Ok(content)
        })
        .await
        .unwrap();

        assert_eq!(content, "version = 4");
    }

    #[test]
    fn test_resolved_packages_new() {
        let packages = ResolvedPackages::new();
        assert!(packages.is_empty());
        assert_eq!(packages.len(), 0);
    }

    #[test]
    fn test_resolved_packages_insert_and_get() {
        let mut packages = ResolvedPackages::new();

        let pkg = ResolvedPackage {
            name: "serde".into(),
            version: "1.0.195".into(),
            source: ResolvedSource::Registry {
                url: "https://github.com/rust-lang/crates.io-index".into(),
                checksum: "abc123".into(),
            },
            dependencies: vec!["serde_derive".into()],
        };

        packages.insert(pkg);

        assert_eq!(packages.len(), 1);
        assert!(!packages.is_empty());
        assert_eq!(packages.version("serde"), Some("1.0.195"));

        let retrieved = packages.get("serde");
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().name, "serde");
        assert_eq!(retrieved.unwrap().dependencies.len(), 1);
    }

    #[test]
    fn test_resolved_packages_get_nonexistent() {
        let packages = ResolvedPackages::new();
        assert_eq!(packages.get("nonexistent"), None);
        assert_eq!(packages.version("nonexistent"), None);
    }

    #[test]
    fn test_resolved_packages_replace() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "1.0.0".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "old".into(),
            },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "1.0.195".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "new".into(),
            },
            dependencies: vec![],
        });

        // Both versions stored, but len counts unique names
        assert_eq!(packages.len(), 1);
        assert_eq!(packages.version("serde"), Some("1.0.195"));
        // Both versions accessible via get_all
        assert_eq!(packages.all("serde").unwrap().len(), 2);
    }

    #[test]
    fn test_resolved_packages_multiple_versions() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "1.0.195".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "a".into(),
            },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "0.9.0".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "b".into(),
            },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "2.0.0-beta.1".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "c".into(),
            },
            dependencies: vec![],
        });

        assert_eq!(packages.len(), 1);
        assert_eq!(packages.version("serde"), Some("2.0.0-beta.1"));
        assert_eq!(packages.all("serde").unwrap().len(), 3);
    }

    #[test]
    fn test_resolved_packages_non_semver_fallback() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "weird".into(),
            version: "abc".into(),
            source: ResolvedSource::Path { path: ".".into() },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "weird".into(),
            version: "xyz".into(),
            source: ResolvedSource::Path { path: ".".into() },
            dependencies: vec![],
        });

        // Falls back to string comparison: "xyz" > "abc"
        assert_eq!(packages.version("weird"), Some("xyz"));
    }

    #[test]
    fn test_resolved_packages_semver_preferred_over_non_semver() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "mixed".into(),
            version: "not-a-version".into(),
            source: ResolvedSource::Path { path: ".".into() },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "mixed".into(),
            version: "1.0.0".into(),
            source: ResolvedSource::Path { path: ".".into() },
            dependencies: vec![],
        });

        // Parseable semver is preferred over non-parseable
        assert_eq!(packages.version("mixed"), Some("1.0.0"));
    }

    #[test]
    fn test_resolved_source_equality() {
        let source1 = ResolvedSource::Registry {
            url: "https://test.com".into(),
            checksum: "abc".into(),
        };
        let source2 = ResolvedSource::Registry {
            url: "https://test.com".into(),
            checksum: "abc".into(),
        };
        let source3 = ResolvedSource::Git {
            url: "https://github.com/test".into(),
            rev: "abc123".into(),
        };

        assert_eq!(source1, source2);
        assert_ne!(source1, source3);
    }

    #[test]
    fn test_resolved_packages_iter() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "1.0.0".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "a".into(),
            },
            dependencies: vec![],
        });

        packages.insert(ResolvedPackage {
            name: "tokio".into(),
            version: "1.0.0".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "b".into(),
            },
            dependencies: vec![],
        });

        let count = packages.iter().count();
        assert_eq!(count, 2);

        let names: Vec<_> = packages.iter().map(|(name, _)| name.as_str()).collect();
        assert!(names.contains(&"serde"));
        assert!(names.contains(&"tokio"));
    }

    #[test]
    fn test_resolved_packages_into_map() {
        let mut packages = ResolvedPackages::new();

        packages.insert(ResolvedPackage {
            name: "serde".into(),
            version: "1.0.0".into(),
            source: ResolvedSource::Registry {
                url: "test".into(),
                checksum: "a".into(),
            },
            dependencies: vec![],
        });

        let map = packages.into_map();
        assert_eq!(map.len(), 1);
        assert!(map.contains_key("serde"));
    }

    #[test]
    fn test_lockfile_cache_new() {
        let cache = LockFileCache::new();
        assert!(cache.is_empty());
        assert_eq!(cache.len(), 0);
        assert_eq!(
            cache.capacity, DEFAULT_MAX_CACHED_LOCKFILES,
            "new() must use the documented default capacity"
        );
    }

    #[test]
    fn test_lockfile_cache_invalidate() {
        let cache = LockFileCache::new();
        let test_path = PathBuf::from("/test/Cargo.lock");

        cache.entries.insert(
            test_path.clone(),
            CachedLockFile {
                packages: ResolvedPackages::new(),
                modified_at: SystemTime::now(),
                parsed_at: Instant::now(),
            },
        );

        assert_eq!(cache.len(), 1);

        cache.invalidate(&test_path);
        assert_eq!(cache.len(), 0);
        assert!(cache.is_empty());
    }

    #[test]
    fn test_lockfile_cache_with_capacity() {
        let cache = LockFileCache::with_capacity(64);
        assert_eq!(cache.capacity, 64);
        assert!(cache.is_empty());
    }

    /// #962 regression: a [`LockFileCache`] at capacity must evict the least-recently-parsed
    /// entry before inserting a new key, never grow past its configured bound.
    #[tokio::test]
    async fn test_get_or_parse_evicts_oldest_entry_at_capacity() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_a = temp_dir.path().join("a.lock");
        let lock_b = temp_dir.path().join("b.lock");
        let lock_c = temp_dir.path().join("c.lock");
        std::fs::write(&lock_a, "a").unwrap();
        std::fs::write(&lock_b, "b").unwrap();
        std::fs::write(&lock_c, "c").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::with_capacity(2);

        cache.get_or_parse(&provider, &lock_a).await.unwrap();
        cache.get_or_parse(&provider, &lock_b).await.unwrap();
        assert_eq!(
            cache.len(),
            2,
            "cache should hold exactly `capacity` entries"
        );

        // `a` is now the oldest by `parsed_at`; inserting a third distinct key must evict
        // it rather than growing the cache past its capacity.
        cache.get_or_parse(&provider, &lock_c).await.unwrap();
        assert_eq!(
            cache.len(),
            2,
            "cache must not grow past its configured capacity"
        );
        assert!(
            cache.entries.contains_key(&lock_b),
            "the more recently parsed entry must survive eviction"
        );
        assert!(
            cache.entries.contains_key(&lock_c),
            "the newly inserted entry must be present"
        );
        assert!(
            !cache.entries.contains_key(&lock_a),
            "the least-recently-parsed entry must have been evicted"
        );

        // Re-fetching the evicted `a` must trigger a fresh parse, not a cache hit.
        let parses_before = provider.parse_count();
        cache.get_or_parse(&provider, &lock_a).await.unwrap();
        assert_eq!(
            provider.parse_count(),
            parses_before + 1,
            "an evicted entry must be re-parsed on next access"
        );
    }

    /// A repeat `get_or_parse` for an already-cached key at capacity must not trigger
    /// eviction — the cache-hit path returns before `entries.insert` is ever reached.
    #[tokio::test]
    async fn test_get_or_parse_cache_hit_at_capacity_does_not_evict() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_a = temp_dir.path().join("a.lock");
        let lock_b = temp_dir.path().join("b.lock");
        std::fs::write(&lock_a, "a").unwrap();
        std::fs::write(&lock_b, "b").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::with_capacity(2);

        cache.get_or_parse(&provider, &lock_a).await.unwrap();
        cache.get_or_parse(&provider, &lock_b).await.unwrap();

        // Re-fetch `a` (unchanged mtime): a cache hit, must not evict `b`.
        cache.get_or_parse(&provider, &lock_a).await.unwrap();
        assert_eq!(cache.len(), 2);
        assert!(cache.entries.contains_key(&lock_a));
        assert!(cache.entries.contains_key(&lock_b));
    }

    #[test]
    fn test_locate_lockfile_for_manifest_same_directory() {
        // Held per `fs_probe::snapshot_guard`'s doc: `locate_lockfile_for_manifest`
        // transitively touches fs_probe (via `fs_probe::is_file`), and this test runs in the
        // same binary as other modules' (e.g. `mtime_cache`'s) diffing tests.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        let lock_path = temp_dir.path().join("Cargo.lock");

        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();
        std::fs::write(&lock_path, "version = 4").unwrap();

        let manifest_uri = Url::from_file_path(&manifest_path).unwrap();
        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(located.is_some());
        assert_eq!(located.unwrap(), lock_path);
    }

    #[test]
    fn test_locate_lockfile_for_manifest_workspace_root() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let workspace_lock = temp_dir.path().join("Cargo.lock");
        let member_dir = temp_dir.path().join("crates").join("member");
        std::fs::create_dir_all(&member_dir).unwrap();
        let member_manifest = member_dir.join("Cargo.toml");

        std::fs::write(&workspace_lock, "version = 4").unwrap();
        std::fs::write(&member_manifest, "[package]\nname = \"member\"").unwrap();

        let manifest_uri = Url::from_file_path(&member_manifest).unwrap();
        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(located.is_some());
        assert_eq!(located.unwrap(), workspace_lock);
    }

    /// #1357 regression guard: `max_ancestor_depth: 0` must find a same-directory lock file
    /// but never walk up to a parent's, while the existing `locate_lockfile_for_manifest`
    /// wrapper must keep finding ancestor lock files for the other ecosystem crates that rely
    /// on it (Cargo, npm, Bundler, etc.).
    #[test]
    fn test_locate_lockfile_for_manifest_with_max_depth_zero_ignores_ancestors() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let workspace_lock = temp_dir.path().join("Cargo.lock");
        let member_dir = temp_dir.path().join("crates").join("member");
        std::fs::create_dir_all(&member_dir).unwrap();
        let member_manifest = member_dir.join("Cargo.toml");
        let member_lock = member_dir.join("Cargo.lock");

        std::fs::write(&workspace_lock, "version = 4").unwrap();
        std::fs::write(&member_manifest, "[package]\nname = \"member\"").unwrap();

        let manifest_uri = Url::from_file_path(&member_manifest).unwrap();

        assert_eq!(
            locate_lockfile_for_manifest_with_max_depth(&manifest_uri, &["Cargo.lock"], 0),
            None,
            "depth 0 must not walk up to the workspace root's lock file"
        );
        assert_eq!(
            locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]),
            Some(workspace_lock),
            "the default wrapper must keep the ancestor-walk behavior for existing callers"
        );

        std::fs::write(&member_lock, "version = 4").unwrap();
        assert_eq!(
            locate_lockfile_for_manifest_with_max_depth(&manifest_uri, &["Cargo.lock"], 0),
            Some(member_lock),
            "depth 0 must still find a lock file in the manifest's own directory"
        );
    }

    /// A directory named `Cargo.lock` (portable stand-in for a FIFO, which
    /// `std::fs::exists`-style checks would also wrongly treat as "found") must not be
    /// returned as a located lock file — `fs_probe::is_file` rejects anything but a
    /// regular file, unlike the plain `Path::exists()` this locator used before the fix.
    #[test]
    fn test_locate_lockfile_for_manifest_skips_non_regular_file() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        let lock_path = temp_dir.path().join("Cargo.lock");

        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();
        std::fs::create_dir(&lock_path).unwrap();

        let manifest_uri = Url::from_file_path(&manifest_path).unwrap();
        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(
            located.is_none(),
            "a directory at the lock file path must not be treated as a found lock file"
        );
    }

    /// #1084 regression: `url::Url::to_file_path` does not check the URI's scheme, so a
    /// hierarchical non-`file:` URI shaped like a real path (e.g. VS Code's `untitled:`
    /// scheme) must be rejected before any filesystem resolution is attempted, never
    /// resolved against the real filesystem.
    #[test]
    fn test_locate_lockfile_for_manifest_rejects_non_file_uri() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        // A real manifest + lockfile pair on disk: without the scheme guard, the unguarded
        // `to_file_path` would still find this lockfile since the path component is real —
        // unlike a nonexistent-directory URI, which would return `None` for an unrelated
        // reason regardless.
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();
        std::fs::write(&lock_path, "version = 4").unwrap();

        let manifest_uri = non_file_uri("untitled:", &manifest_path);

        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(
            located.is_none(),
            "a non-file-scheme URI must never resolve to a filesystem path, even when that \
             path names a real, existing lock file"
        );
    }

    /// #1084 S3: a `file://` URI carrying a non-`localhost` host must be rejected by
    /// [`resolve_manifest_file_path`], not resolved against the local filesystem as if the
    /// host were not there. `url::Url::to_file_path` already refuses this internally
    /// (verified empirically: it checks cannot-be-a-base and host), but the explicit host
    /// check in `resolve_manifest_file_path` pins the behavior at this call site regardless
    /// of that internal detail, so this test protects against either implementation
    /// drifting silently.
    ///
    /// `#[cfg(unix)]`: the WHATWG URL Standard's file-host parsing unconditionally drops a
    /// `file://` URL's host whenever the path immediately following it looks like a Windows
    /// drive letter (`url` crate's `parser.rs`: "For file URLs that have a host and whose
    /// path starts with the windows drive letter we just remove the host" — this is
    /// spec-mandated parsing behavior, not an OS-gated code path, but it only *triggers* on
    /// a real Windows machine, where `tempfile::tempdir()`'s absolute path is drive-lettered;
    /// on Unix the path never looks like a drive letter, so the host survives parsing).
    /// Concretely: `file://attacker.example/C:/x` parses with `host: None`, not
    /// `Some("attacker.example")`, on Windows — the malicious host is discarded before
    /// `resolve_manifest_file_path` ever sees it, and the URI resolves to the local
    /// drive-letter path directly, same as if no host had been specified at all. This is
    /// safe (the "remote host" never actually gets treated as a target), just not what this
    /// test's `assert!(located.is_none())` expects, so it is Unix-only rather than adjusted
    /// to a different, weaker assertion guessed at without a Windows environment to verify
    /// the exact resulting behavior against.
    #[cfg(unix)]
    #[test]
    fn test_locate_lockfile_for_manifest_rejects_remote_host_file_uri() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();
        std::fs::write(&lock_path, "version = 4").unwrap();

        let manifest_uri = non_file_uri("file://attacker.example", &manifest_path);

        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(
            located.is_none(),
            "a file: URI carrying a non-localhost host must never resolve to a filesystem path"
        );
    }

    /// A `file:` URI with an empty or `localhost` host must still resolve normally — the
    /// host guard in [`resolve_manifest_file_path`] must not reject the common, safe case.
    ///
    /// `#[cfg(unix)]`: this crate's other Windows-path tests (see `deps_core::test_util::
    /// test_uri` and the `#1071` migration handoffs) establish that `url::Url::to_file_path`
    /// needs a drive-letter-shaped first path segment to resolve on Windows at all; a bare
    /// `file://localhost/tmp/...`-style fixture with no drive letter is not a portable test
    /// input there, so this is kept Unix-only rather than guessed at without a Windows
    /// environment to verify against.
    #[cfg(unix)]
    #[test]
    fn test_locate_lockfile_for_manifest_accepts_localhost_file_uri() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        let lock_path = temp_dir.path().join("Cargo.lock");
        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();
        std::fs::write(&lock_path, "version = 4").unwrap();

        let manifest_uri = non_file_uri("file://localhost", &manifest_path);

        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert_eq!(located, Some(lock_path));
    }

    #[test]
    fn test_locate_lockfile_for_manifest_not_found() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("Cargo.toml");
        std::fs::write(&manifest_path, "[package]\nname = \"test\"").unwrap();

        let manifest_uri = Url::from_file_path(&manifest_path).unwrap();
        let located = locate_lockfile_for_manifest(&manifest_uri, &["Cargo.lock"]);

        assert!(located.is_none());
    }

    #[test]
    fn test_locate_lockfile_for_manifest_multiple_names() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("pyproject.toml");
        let uv_lock = temp_dir.path().join("uv.lock");

        std::fs::write(&manifest_path, "[project]\nname = \"test\"").unwrap();
        std::fs::write(&uv_lock, "version = 1").unwrap();

        let manifest_uri = Url::from_file_path(&manifest_path).unwrap();
        // poetry.lock doesn't exist, but uv.lock does - should find uv.lock
        let located = locate_lockfile_for_manifest(&manifest_uri, &["poetry.lock", "uv.lock"]);

        assert!(located.is_some());
        assert_eq!(located.unwrap(), uv_lock);
    }

    /// Stub [`LockFileProvider`] that counts `parse_lockfile` invocations and returns
    /// a package whose version is the lock file's trimmed content, so tests can
    /// observe both call count and which content was actually parsed.
    struct CountingLockFileProvider {
        parse_count: std::sync::atomic::AtomicUsize,
    }

    impl CountingLockFileProvider {
        fn new() -> Self {
            Self {
                parse_count: std::sync::atomic::AtomicUsize::new(0),
            }
        }

        fn parse_count(&self) -> usize {
            self.parse_count.load(std::sync::atomic::Ordering::SeqCst)
        }
    }

    impl LockFileProvider for CountingLockFileProvider {
        fn locate_lockfile(&self, _manifest_uri: &Url) -> Option<PathBuf> {
            None
        }

        fn parse_lockfile<'a>(
            &'a self,
            lockfile_path: &'a Path,
        ) -> std::pin::Pin<
            Box<dyn std::future::Future<Output = Result<ResolvedPackages>> + Send + 'a>,
        > {
            Box::pin(async move {
                self.parse_count
                    .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                let content = read_lockfile_content(lockfile_path, "test.lock").await?;

                let mut packages = ResolvedPackages::new();
                packages.insert(ResolvedPackage {
                    name: "test-package".into(),
                    version: content.trim().to_string(),
                    source: ResolvedSource::Path { path: ".".into() },
                    dependencies: vec![],
                });
                Ok(packages)
            })
        }
    }

    #[tokio::test]
    async fn test_get_or_parse_cache_hit_does_not_reparse() {
        // Held per `fs_probe::snapshot_guard`'s doc: the stub provider's `parse_lockfile`
        // calls `read_lockfile_content`, which transitively touches fs_probe.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("test.lock");
        std::fs::write(&lock_path, "1.0.0").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::new();

        let first = cache.get_or_parse(&provider, &lock_path).await.unwrap();
        let second = cache.get_or_parse(&provider, &lock_path).await.unwrap();

        assert_eq!(provider.parse_count(), 1, "second call should hit cache");
        assert_eq!(first.version("test-package"), Some("1.0.0"));
        assert_eq!(second.version("test-package"), Some("1.0.0"));
    }

    /// A lock file that does not exist (never cached, or deleted since) must surface as an
    /// `Err`, not panic or silently return empty/stale data — `get_or_parse` has no dedicated
    /// missing-file branch of its own; its cache-miss path's `tokio::fs::metadata` stat simply
    /// propagates the failure via `?`.
    #[tokio::test]
    async fn test_get_or_parse_missing_file_returns_error() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("does-not-exist.lock");

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::new();

        let err = cache.get_or_parse(&provider, &lock_path).await.unwrap_err();

        assert!(
            matches!(err, DepsError::Io(_)),
            "expected an Io error for a missing lock file, got: {err:?}"
        );
        assert_eq!(
            provider.parse_count(),
            0,
            "parse_lockfile must not be called when the file cannot be stat'd"
        );
    }

    /// A cached entry whose backing file has since been deleted must not be served as a
    /// stale-but-valid cache hit: the freshness check's stat fails, falls through to the
    /// cache-miss path, and that path's own stat also fails, surfacing as `Err` rather than
    /// resurrecting the old cached packages.
    #[tokio::test]
    async fn test_get_or_parse_cached_entry_with_deleted_file_returns_error() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("test.lock");
        std::fs::write(&lock_path, "1.0.0").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::new();

        let first = cache.get_or_parse(&provider, &lock_path).await.unwrap();
        assert_eq!(first.version("test-package"), Some("1.0.0"));

        std::fs::remove_file(&lock_path).unwrap();

        let err = cache.get_or_parse(&provider, &lock_path).await.unwrap_err();

        assert!(
            matches!(err, DepsError::Io(_)),
            "expected an Io error once the cached file is deleted, got: {err:?}"
        );
    }

    #[tokio::test]
    async fn test_get_or_parse_reparses_when_mtime_advances() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("test.lock");
        std::fs::write(&lock_path, "1.0.0").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::new();

        let first = cache.get_or_parse(&provider, &lock_path).await.unwrap();
        assert_eq!(first.version("test-package"), Some("1.0.0"));

        std::fs::write(&lock_path, "2.0.0").unwrap();
        // Explicitly bump mtime into the future rather than relying on filesystem
        // mtime resolution (coarse on some platforms) to observe the change.
        let future_mtime = SystemTime::now() + std::time::Duration::from_secs(5);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&lock_path)
            .unwrap()
            .set_modified(future_mtime)
            .unwrap();

        let second = cache.get_or_parse(&provider, &lock_path).await.unwrap();

        assert_eq!(
            provider.parse_count(),
            2,
            "stale mtime should trigger reparse"
        );
        assert_eq!(second.version("test-package"), Some("2.0.0"));
    }

    /// Documents intentional behavior, not a bug: if a lock file's mtime moves *backward*
    /// relative to what is cached (clock skew, a restored backup, a `git checkout` touching
    /// an older tree), `get_or_parse`'s freshness check (`mtime <= cached_modified_at`) treats
    /// it as still fresh and serves the cached (now content-stale) packages rather than
    /// re-parsing. This mirrors the removed `is_lockfile_stale` default's own behavior for a
    /// `last_modified` timestamp set to the future, so the semantics are unchanged by its
    /// removal — this test exists only so the choice stays covered and visible.
    #[tokio::test]
    async fn test_get_or_parse_cache_hit_when_mtime_moves_backward() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("test.lock");
        std::fs::write(&lock_path, "1.0.0").unwrap();

        let provider = CountingLockFileProvider::new();
        let cache = LockFileCache::new();

        let first = cache.get_or_parse(&provider, &lock_path).await.unwrap();
        assert_eq!(first.version("test-package"), Some("1.0.0"));

        std::fs::write(&lock_path, "2.0.0").unwrap();
        let past_mtime = SystemTime::now() - std::time::Duration::from_secs(3600);
        std::fs::OpenOptions::new()
            .write(true)
            .open(&lock_path)
            .unwrap()
            .set_modified(past_mtime)
            .unwrap();

        let second = cache.get_or_parse(&provider, &lock_path).await.unwrap();

        assert_eq!(
            provider.parse_count(),
            1,
            "a backward-moving mtime must still be treated as a cache hit"
        );
        assert_eq!(
            second.version("test-package"),
            Some("1.0.0"),
            "cached (pre-rewrite) content should be served, not the new on-disk content"
        );
    }

    /// Stub [`LockFileProvider`] that simulates a concurrent writer racing the parse:
    /// each `parse_lockfile` call reads the file's *current* content first, then — as
    /// a side effect before returning — rewrites the file to `"2.0.0"` and bumps its
    /// mtime into the future, then returns packages parsed from the content it read
    /// *before* that rewrite. This reproduces the only await point between the
    /// `get_or_parse` stat and cache insert, entirely under test control.
    struct RewritingDuringParseProvider {
        parse_count: std::sync::atomic::AtomicUsize,
    }

    impl RewritingDuringParseProvider {
        fn new() -> Self {
            Self {
                parse_count: std::sync::atomic::AtomicUsize::new(0),
            }
        }

        fn parse_count(&self) -> usize {
            self.parse_count.load(std::sync::atomic::Ordering::SeqCst)
        }
    }

    impl LockFileProvider for RewritingDuringParseProvider {
        fn locate_lockfile(&self, _manifest_uri: &Url) -> Option<PathBuf> {
            None
        }

        fn parse_lockfile<'a>(
            &'a self,
            lockfile_path: &'a Path,
        ) -> std::pin::Pin<
            Box<dyn std::future::Future<Output = Result<ResolvedPackages>> + Send + 'a>,
        > {
            Box::pin(async move {
                self.parse_count
                    .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                let content = read_lockfile_content(lockfile_path, "test.lock").await?;

                // Simulate a writer rewriting the lock file mid-parse.
                std::fs::write(lockfile_path, "2.0.0").unwrap();
                let future_mtime = SystemTime::now() + std::time::Duration::from_secs(5);
                std::fs::OpenOptions::new()
                    .write(true)
                    .open(lockfile_path)
                    .unwrap()
                    .set_modified(future_mtime)
                    .unwrap();

                let mut packages = ResolvedPackages::new();
                packages.insert(ResolvedPackage {
                    name: "test-package".into(),
                    version: content.trim().to_string(),
                    source: ResolvedSource::Path { path: ".".into() },
                    dependencies: vec![],
                });
                Ok(packages)
            })
        }
    }

    /// Regression test for #359: discriminates the stat-before-parse fix from the
    /// original stat-after-parse ordering.
    ///
    /// With the fix, `get_or_parse` stats the file *before* calling `parse_lockfile`,
    /// so the cached `modified_at` reflects the pre-rewrite mtime tied to the
    /// `"1.0.0"` content actually parsed. A second call then sees the file's mtime is
    /// newer than the cached one, so it re-parses and observes `"2.0.0"`.
    ///
    /// On the pre-fix ordering (stat after parse), the post-parse stat would pick up
    /// the mtime bump this same call just made, storing the *new* mtime alongside the
    /// *old* (`"1.0.0"`) content. The second call would then incorrectly hit cache and
    /// return stale `"1.0.0"` content without re-parsing — exactly the bug #359
    /// describes. This test would have failed on that code.
    #[tokio::test]
    async fn test_get_or_parse_detects_rewrite_during_parse() {
        // See the comment in `test_get_or_parse_cache_hit_does_not_reparse` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard_async().await;
        let temp_dir = tempfile::tempdir().unwrap();
        let lock_path = temp_dir.path().join("test.lock");
        std::fs::write(&lock_path, "1.0.0").unwrap();

        let provider = RewritingDuringParseProvider::new();
        let cache = LockFileCache::new();

        let first = cache.get_or_parse(&provider, &lock_path).await.unwrap();
        assert_eq!(first.version("test-package"), Some("1.0.0"));

        let second = cache.get_or_parse(&provider, &lock_path).await.unwrap();

        assert_eq!(
            provider.parse_count(),
            2,
            "rewrite during first parse must be detected and trigger a reparse"
        );
        assert_eq!(second.version("test-package"), Some("2.0.0"));
    }

    #[test]
    fn test_locate_lockfile_for_manifest_first_match_wins() {
        // See the comment in `test_locate_lockfile_for_manifest_same_directory` on why this
        // guard is needed here.
        let _guard = fs_probe::snapshot_guard();
        let temp_dir = tempfile::tempdir().unwrap();
        let manifest_path = temp_dir.path().join("pyproject.toml");
        let poetry_lock = temp_dir.path().join("poetry.lock");
        let uv_lock = temp_dir.path().join("uv.lock");

        std::fs::write(&manifest_path, "[project]\nname = \"test\"").unwrap();
        std::fs::write(&poetry_lock, "# poetry lock").unwrap();
        std::fs::write(&uv_lock, "version = 1").unwrap();

        let manifest_uri = Url::from_file_path(&manifest_path).unwrap();
        // Both exist, poetry.lock should be found first (listed first)
        let located = locate_lockfile_for_manifest(&manifest_uri, &["poetry.lock", "uv.lock"]);

        assert!(located.is_some());
        assert_eq!(located.unwrap(), poetry_lock);
    }

    crate::debug_redaction_conformance!(
        test_resolved_package_debug_redacts_credentials,
        3,
        ResolvedPackage {
            name: crate::conformance::CREDENTIAL_PROBE_KEY.to_string(),
            version: "1.0.0".to_string(),
            source: ResolvedSource::Git {
                url: crate::conformance::CREDENTIAL_PROBE_URL.to_string(),
                rev: "deadbeef".to_string(),
            },
            dependencies: vec![crate::conformance::CREDENTIAL_PROBE_KEY.to_string()],
        },
    );

    crate::debug_redaction_conformance!(
        test_resolved_source_registry_debug_redacts_credentials,
        1,
        ResolvedSource::Registry {
            url: crate::conformance::CREDENTIAL_PROBE_URL.to_string(),
            checksum: "abc123".to_string(),
        },
    );

    // Regression for #1237 S3: `Path` is `parse_cargo_source`'s catch-all for any source
    // prefix it doesn't recognize (`sparse+` itself is classified as `Registry` since #1320),
    // so `Path`'s `path` field must still redact a credential for whatever unrecognized prefix
    // reaches it.
    crate::debug_redaction_conformance!(
        test_resolved_source_path_debug_redacts_unrecognized_scheme_credential,
        1,
        ResolvedSource::Path {
            path: format!(
                "unknown-scheme+{}",
                crate::conformance::CREDENTIAL_PROBE_URL
            ),
        },
    );

    // #1319 M3: plants the probe in both the map key and `ResolvedPackage.name` — the shape
    // `ResolvedPackages::insert` always produces (key == value.name) — so this also locks the
    // duplicated-name scenario the issue is about, not just an unrealistic key/name mismatch.
    crate::debug_redaction_conformance!(
        test_resolved_packages_debug_redacts_map_key,
        2,
        ResolvedPackages {
            packages: HashMap::from([(
                crate::conformance::CREDENTIAL_PROBE_KEY.to_string(),
                vec![ResolvedPackage::new(
                    crate::conformance::CREDENTIAL_PROBE_KEY.to_string(),
                    "1.0.0".to_string(),
                    ResolvedSource::Path {
                        path: String::new(),
                    },
                )],
            )]),
        },
    );

    #[test]
    fn test_resolved_packages_debug_preserves_colliding_redacted_keys() {
        // Two distinct raw names that redact to the identical marker `***@git.internal.corp`
        // (#1319 S2 regression guard): a naive `.collect::<HashMap<_, _>>()` over the redacted
        // keys would collapse both into one map entry, silently dropping a package from the
        // rendered output. The `debug_map()`-based impl must emit one entry per original
        // package regardless of redacted-key collisions.
        let name_a = "orgA:deployA:secretA@git.internal.corp";
        let name_b = "orgB.other:deployB:secretB@git.internal.corp";

        let mut packages = ResolvedPackages::new();
        packages.insert(ResolvedPackage::new(
            name_a.to_string(),
            "1.0.0".to_string(),
            ResolvedSource::Path {
                path: String::new(),
            },
        ));
        packages.insert(ResolvedPackage::new(
            name_b.to_string(),
            "2.0.0".to_string(),
            ResolvedSource::Path {
                path: String::new(),
            },
        ));

        assert_eq!(packages.len(), 2);

        let rendered = format!("{packages:?}");

        assert!(!rendered.contains("secretA"));
        assert!(!rendered.contains("secretB"));
        assert!(
            rendered.contains("1.0.0"),
            "package a's version must survive: {rendered}"
        );
        assert!(
            rendered.contains("2.0.0"),
            "package b's version must survive: {rendered}"
        );
        assert_eq!(
            rendered.matches("***@git.internal.corp").count(),
            4,
            "expected 2 redacted map keys + 2 redacted ResolvedPackage.name fields, found: {rendered}"
        );
    }
}