dnx_core/

resolver.rs

use crate::errors::{DnxError, Result};
use crate::hooks::{HookPackage, Hooks};
use crate::registry::{PackageMetadata, RegistryClient, VersionMetadata};
use serde::{Deserialize, Serialize};
use std::cell::RefCell;
use std::collections::{HashMap, VecDeque};
use std::sync::Arc;
use tracing::{debug, trace, warn};

// Thread-local caches for parsed semver values to avoid re-parsing on every call
thread_local! {
    static VERSION_CACHE: RefCell<HashMap<String, Option<node_semver::Version>>> =
        RefCell::new(HashMap::new());
    static RANGE_CACHE: RefCell<HashMap<String, Option<node_semver::Range>>> =
        RefCell::new(HashMap::new());
}

fn cached_parse_version(s: &str) -> Option<node_semver::Version> {
    VERSION_CACHE.with(|cache| {
        let mut cache = cache.borrow_mut();
        cache
            .entry(s.to_string())
            .or_insert_with(|| node_semver::Version::parse(s).ok())
            .clone()
    })
}

fn cached_parse_range(s: &str) -> Option<node_semver::Range> {
    RANGE_CACHE.with(|cache| {
        let mut cache = cache.borrow_mut();
        cache
            .entry(s.to_string())
            .or_insert_with(|| node_semver::Range::parse(s).ok())
            .clone()
    })
}

// ---------------------------------------------------------------------------
// Dependency spec types
// ---------------------------------------------------------------------------

/// Parsed dependency specifier — determines how to resolve a dependency.
#[derive(Debug, Clone)]
pub enum DependencySpec {
    /// Standard semver range (e.g. "^1.0.0", "~2.3", ">=0.0.0").
    Semver { range: String },
    /// npm alias (e.g. "npm:strip-ansi@^6.0.1") — resolves `real_name` at `range`
    /// but installs under the dependency key's name.
    Alias { real_name: String, range: String },
    /// Git URL (e.g. "git+https://github.com/user/repo.git#ref").
    Git {
        url: String,
        reference: Option<String>,
    },
    /// GitHub shorthand (e.g. "user/repo", "user/repo#branch").
    Github {
        user: String,
        repo: String,
        reference: Option<String>,
    },
    /// Local file path (e.g. "file:../my-lib").
    File { path: String },
    /// Symlink (e.g. "link:../my-lib").
    Link { path: String },
    /// Workspace reference (e.g. "workspace:*", "workspace:^", "workspace:~1.0.0").
    Workspace { range: String },
    /// Catalog reference (e.g. "catalog:", "catalog:testing").
    Catalog { catalog_name: Option<String> },
}

impl DependencySpec {
    /// Parse a version/range string into a DependencySpec.
    pub fn parse(spec: &str) -> Self {
        let spec = spec.trim();

        // workspace: protocol
        if let Some(suffix) = spec.strip_prefix("workspace:") {
            return DependencySpec::Workspace {
                range: suffix.to_string(),
            };
        }

        // catalog: protocol
        if let Some(suffix) = spec.strip_prefix("catalog:") {
            return DependencySpec::Catalog {
                catalog_name: if suffix.is_empty() {
                    None
                } else {
                    Some(suffix.to_string())
                },
            };
        }

        // npm: alias protocol — e.g. "npm:strip-ansi@^6.0.1" or "npm:@scope/pkg@^1.0"
        if let Some(rest) = spec.strip_prefix("npm:") {
            // after "npm:"
            // Parse "real-name@range" — handle scoped packages
            let (real_name, range) = if let Some(stripped) = rest.strip_prefix('@') {
                // Scoped: "@scope/pkg@^1.0.0"
                if let Some(idx) = stripped.find('@') {
                    (rest[..idx + 1].to_string(), stripped[idx + 1..].to_string())
                } else {
                    (rest.to_string(), "*".to_string())
                }
            } else if let Some(idx) = rest.find('@') {
                (rest[..idx].to_string(), rest[idx + 1..].to_string())
            } else {
                (rest.to_string(), "*".to_string())
            };
            return DependencySpec::Alias { real_name, range };
        }

        // link: protocol — always symlinked, never copied
        if let Some(suffix) = spec.strip_prefix("link:") {
            return DependencySpec::Link {
                path: suffix.to_string(),
            };
        }

        // file: protocol — local tarball or directory
        if let Some(suffix) = spec.strip_prefix("file:") {
            return DependencySpec::File {
                path: suffix.to_string(),
            };
        }

        // git+ protocols
        if spec.starts_with("git+") || spec.starts_with("git://") {
            let url_part = if let Some(stripped) = spec.strip_prefix("git+") {
                stripped
            } else {
                spec
            };
            let (url, reference) = if let Some(idx) = url_part.find('#') {
                (
                    url_part[..idx].to_string(),
                    Some(url_part[idx + 1..].to_string()),
                )
            } else {
                (url_part.to_string(), None)
            };
            return DependencySpec::Git { url, reference };
        }

        // https:// git URLs (common for GitHub)
        if (spec.starts_with("https://") || spec.starts_with("http://")) && spec.contains(".git") {
            let (url, reference) = if let Some(idx) = spec.find('#') {
                (spec[..idx].to_string(), Some(spec[idx + 1..].to_string()))
            } else {
                (spec.to_string(), None)
            };
            return DependencySpec::Git { url, reference };
        }

        // GitHub shorthand: "user/repo" or "user/repo#ref"
        // Must contain exactly one slash, no @ at start, no protocol
        if !spec.starts_with('@') && !spec.contains("://") && spec.contains('/') {
            let (base, reference) = if let Some(idx) = spec.find('#') {
                (&spec[..idx], Some(spec[idx + 1..].to_string()))
            } else {
                (spec, None)
            };
            let parts: Vec<&str> = base.splitn(2, '/').collect();
            if parts.len() == 2 && !parts[0].is_empty() && !parts[1].is_empty() {
                return DependencySpec::Github {
                    user: parts[0].to_string(),
                    repo: parts[1].to_string(),
                    reference,
                };
            }
        }

        // Default: semver range
        DependencySpec::Semver {
            range: spec.to_string(),
        }
    }

    /// Returns true if this is a standard semver range.
    pub fn is_semver(&self) -> bool {
        matches!(self, DependencySpec::Semver { .. })
    }
}

// ---------------------------------------------------------------------------
// Public types
// ---------------------------------------------------------------------------

/// A single resolved package with everything needed for fetching and linking.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolvedPackage {
    /// Package name (e.g. "react" or "@babel/core").
    pub name: String,
    /// Exact resolved version string (e.g. "18.2.0").
    pub version: String,
    /// Registry tarball URL.
    pub tarball_url: String,
    /// Integrity hash – prefers `integrity` (subresource integrity format)
    /// and falls back to `shasum`.
    pub integrity: String,
    /// Direct dependency references in `"name@version"` format.
    pub dependencies: Vec<String>,
    /// Peer dependency references in `"name@version"` format.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub peer_dependencies: Vec<String>,
    /// Executable binaries exposed by this package.
    pub bin: HashMap<String, String>,
    /// Whether this package has install scripts (preinstall, install, postinstall).
    #[serde(default)]
    pub has_install_script: bool,
}

/// The full dependency graph produced by the resolver.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DependencyGraph {
    pub packages: Vec<ResolvedPackage>,
}

/// Greedy dependency resolver.
///
/// The algorithm walks the dependency tree breadth-first, always picking the
/// highest version that satisfies each requested semver range.  When two
/// different parts of the tree request the same package with compatible
/// ranges the already-resolved version is reused; when an incompatible range
/// is encountered we keep the *first* resolved version (similar to npm
/// flat-mode) and emit a warning.
pub struct Resolver {
    registry: Arc<RegistryClient>,
    /// Override map: package name → forced version/range.
    overrides: HashMap<String, String>,
    /// Workspace packages: name → (version, path). When a dependency resolves
    /// to a workspace member, it is linked locally instead of fetched.
    workspace_packages: HashMap<String, (String, std::path::PathBuf)>,
    /// Whether to automatically install peer dependencies when they are not satisfied.
    auto_install_peers: bool,
    /// Hook system for .pnpmfile.cjs — wrapped in RefCell for interior mutability.
    hooks: RefCell<Hooks>,
}

// ---------------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------------

/// Work item for the resolution queue.
#[derive(Debug)]
struct QueueEntry {
    name: String,
    /// The raw version range string from the dependant's `dependencies` map.
    range: String,
    /// Whether this dependency is optional (failures are non-fatal).
    optional: bool,
}

/// Find the highest version in `metadata` that satisfies `range_str`.
///
/// If an override version is provided, it takes precedence over range matching.
///
/// Special cases handled:
/// - `"*"` and `""` are treated as `">=0.0.0"` (any version).
/// - `"latest"` (or any other dist-tag) is resolved via `dist_tags` first;
///   if the tag is not present it is tried as a regular semver range.
/// - Pure URL/tarball/git references are not supported and will error.
fn find_best_version<'a>(
    metadata: &'a PackageMetadata,
    range_str: &str,
    override_version: Option<&str>,
) -> Result<(String, &'a VersionMetadata)> {
    // If an override is specified, use it instead of the range
    let range_str = override_version.unwrap_or(range_str);
    let range_str = range_str.trim();

    // ---- Handle dist-tag references (e.g. "latest", "next", "canary") ----
    if let Some(tag_version) = metadata.dist_tags.get(range_str) {
        if let Some(vm) = metadata.versions.get(tag_version) {
            return Ok((tag_version.clone(), vm));
        }
        // Tag exists but the pointed-to version is missing – fall through to
        // range-based resolution.
    }

    // ---- Normalise wildcard / empty ranges ----
    let effective_range = match range_str {
        "" | "*" | "latest" => ">=0.0.0".to_string(),
        s => s.to_string(),
    };

    // ---- Parse the semver range ----
    let range = cached_parse_range(&effective_range).ok_or_else(|| {
        DnxError::Resolution(format!(
            "Invalid semver range '{}' for package '{}': parse error",
            range_str, metadata.name
        ))
    })?;

    // ---- Collect & sort candidate versions descending ----
    let mut candidates: Vec<(node_semver::Version, &str)> = Vec::new();

    for ver_str in metadata.versions.keys() {
        if let Some(v) = cached_parse_version(ver_str) {
            // Skip pre-release versions unless the range explicitly mentions one.
            if !v.pre_release.is_empty() && !range_str.contains('-') {
                continue;
            }
            candidates.push((v, ver_str.as_str()));
        }
    }

    // Sort descending so the first match is the highest satisfying version.
    candidates.sort_by(|a, b| b.0.cmp(&a.0));

    for (ver, ver_str) in &candidates {
        if range.satisfies(ver) {
            let vm = metadata.versions.get(*ver_str).unwrap();
            return Ok((ver_str.to_string(), vm));
        }
    }

    Err(DnxError::Resolution(format!(
        "No version of '{}' satisfies range '{}'",
        metadata.name, range_str
    )))
}

/// Check whether a package version is compatible with the current platform.
///
/// Returns `true` if the package can run on this OS + CPU combination.
/// npm semantics: if the field is absent, any platform is fine.
/// A leading `!` in a list entry means "exclude this platform".
fn is_platform_compatible(version_meta: &VersionMetadata) -> bool {
    if let Some(ref os_list) = version_meta.os {
        if !os_list.is_empty() && !check_platform_list(os_list, current_os()) {
            return false;
        }
    }
    if let Some(ref cpu_list) = version_meta.cpu {
        if !cpu_list.is_empty() && !check_platform_list(cpu_list, current_cpu()) {
            return false;
        }
    }
    true
}

/// Check a platform list against a target value.
/// Lists can be allow-lists (`["linux", "darwin"]`) or deny-lists (`["!win32"]`).
fn check_platform_list(list: &[String], target: &str) -> bool {
    let has_negations = list.iter().any(|s| s.starts_with('!'));
    let has_positives = list.iter().any(|s| !s.starts_with('!'));

    // If there are negation entries, check none of them match
    if has_negations {
        for entry in list {
            if let Some(excluded) = entry.strip_prefix('!') {
                if excluded == target {
                    return false;
                }
            }
        }
    }

    // If there are positive entries, target must be in the list
    if has_positives {
        return list.iter().any(|s| !s.starts_with('!') && s == target);
    }

    // Only negations and none matched — compatible
    true
}

/// Get the current OS name in npm conventions.
fn current_os() -> &'static str {
    if cfg!(target_os = "windows") {
        "win32"
    } else if cfg!(target_os = "macos") {
        "darwin"
    } else if cfg!(target_os = "linux") {
        "linux"
    } else if cfg!(target_os = "freebsd") {
        "freebsd"
    } else if cfg!(target_os = "openbsd") {
        "openbsd"
    } else {
        "unknown"
    }
}

/// Get the current CPU architecture in npm conventions.
fn current_cpu() -> &'static str {
    if cfg!(target_arch = "x86_64") {
        "x64"
    } else if cfg!(target_arch = "aarch64") {
        "arm64"
    } else if cfg!(target_arch = "x86") {
        "ia32"
    } else if cfg!(target_arch = "arm") {
        "arm"
    } else {
        "unknown"
    }
}

/// Extract the `bin` field from a VersionMetadata into a flat map.
///
/// npm packages declare `bin` in three ways:
/// - Not present → empty map.
/// - A single string → `{ <package_name>: <path> }`.
/// - An object mapping command names to paths.
fn extract_bin(bin: &Option<serde_json::Value>, package_name: &str) -> HashMap<String, String> {
    let mut map = HashMap::new();
    match bin {
        None => {}
        Some(serde_json::Value::String(s)) => {
            // Use the unscoped portion of the name as the command name.
            let cmd = if let Some(idx) = package_name.rfind('/') {
                &package_name[idx + 1..]
            } else {
                package_name
            };
            map.insert(cmd.to_string(), s.clone());
        }
        Some(serde_json::Value::Object(obj)) => {
            for (key, val) in obj {
                if let serde_json::Value::String(s) = val {
                    map.insert(key.clone(), s.clone());
                }
            }
        }
        _ => {
            warn!(
                "Unexpected bin format for package '{}': {:?}",
                package_name, bin
            );
        }
    }
    map
}

/// Build an integrity string preferring the subresource-integrity value.
/// Returns empty string if no usable integrity is available; the cache layer
/// will compute SHA-512 from the downloaded tarball in that case.
fn integrity_string(dist: &crate::registry::DistInfo) -> String {
    if let Some(ref integrity) = dist.integrity {
        if !integrity.is_empty() && integrity.starts_with("sha512-") {
            return integrity.clone();
        }
    }
    // Accept sha384 or other non-sha1 integrity formats
    if let Some(ref integrity) = dist.integrity {
        if !integrity.is_empty() && !integrity.starts_with("sha1-") {
            return integrity.clone();
        }
    }
    // No integrity field available - this will be handled by cache.store()
    // which computes SHA-512 from the downloaded tarball data
    String::new()
}

/// Return type for the readPackage hook: (dependencies, optional_dependencies, peer_dependencies).
type OptionalDepsTriple = (
    Option<HashMap<String, String>>,
    Option<HashMap<String, String>>,
    Option<HashMap<String, String>>,
);

// ---------------------------------------------------------------------------
// Resolver implementation
// ---------------------------------------------------------------------------

impl Resolver {
    /// Create a new resolver backed by the given registry client.
    pub fn new(registry: Arc<RegistryClient>) -> Self {
        Self {
            registry,
            overrides: HashMap::new(),
            workspace_packages: HashMap::new(),
            auto_install_peers: true,
            hooks: RefCell::new(Hooks::Noop),
        }
    }

    /// Create a new resolver with overrides for forced version resolution.
    pub fn with_overrides(
        registry: Arc<RegistryClient>,
        overrides: HashMap<String, String>,
    ) -> Self {
        Self {
            registry,
            overrides,
            workspace_packages: HashMap::new(),
            auto_install_peers: true,
            hooks: RefCell::new(Hooks::Noop),
        }
    }

    /// Create a new resolver with workspace package information.
    pub fn with_workspace(
        registry: Arc<RegistryClient>,
        overrides: HashMap<String, String>,
        workspace_packages: HashMap<String, (String, std::path::PathBuf)>,
    ) -> Self {
        Self {
            registry,
            overrides,
            workspace_packages,
            auto_install_peers: true,
            hooks: RefCell::new(Hooks::Noop),
        }
    }

    /// Set the hook system for this resolver.
    pub fn set_hooks(&self, hooks: Hooks) {
        *self.hooks.borrow_mut() = hooks;
    }

    /// Enable or disable automatic peer dependency installation.
    pub fn set_auto_install_peers(&mut self, enabled: bool) {
        self.auto_install_peers = enabled;
    }

    /// Apply readPackage hook to a version's dependency maps.
    /// Returns potentially modified (dependencies, optional_dependencies, peer_dependencies).
    fn apply_read_package_hook(
        &self,
        name: &str,
        version: &str,
        deps: &Option<HashMap<String, String>>,
        opt_deps: &Option<HashMap<String, String>>,
        peer_deps: &Option<HashMap<String, String>>,
    ) -> OptionalDepsTriple {
        let mut hooks = self.hooks.borrow_mut();
        if !hooks.is_active() {
            return (deps.clone(), opt_deps.clone(), peer_deps.clone());
        }

        let hook_pkg = HookPackage {
            name: name.to_string(),
            version: version.to_string(),
            dependencies: deps.clone().unwrap_or_default(),
            dev_dependencies: HashMap::new(),
            peer_dependencies: peer_deps.clone().unwrap_or_default(),
            optional_dependencies: opt_deps.clone().unwrap_or_default(),
        };

        match hooks.read_package(hook_pkg) {
            Ok(modified) => {
                let new_deps = if modified.dependencies.is_empty() {
                    None
                } else {
                    Some(modified.dependencies)
                };
                let new_opt = if modified.optional_dependencies.is_empty() {
                    None
                } else {
                    Some(modified.optional_dependencies)
                };
                let new_peers = if modified.peer_dependencies.is_empty() {
                    None
                } else {
                    Some(modified.peer_dependencies)
                };
                (new_deps, new_opt, new_peers)
            }
            Err(e) => {
                warn!("readPackage hook failed for {}@{}: {}", name, version, e);
                (deps.clone(), opt_deps.clone(), peer_deps.clone())
            }
        }
    }

    /// Resolve a set of root dependencies into a flat dependency graph.
    ///
    /// `root_deps` maps package names to semver range strings, exactly as
    /// they appear in `package.json` under `dependencies`.
    ///
    /// Uses a batch-drain BFS: drains up to 32 entries from the queue,
    /// fetches all missing metadata concurrently, then processes the batch.
    pub async fn resolve(&self, root_deps: &HashMap<String, String>) -> Result<DependencyGraph> {
        if root_deps.is_empty() {
            return Ok(DependencyGraph {
                packages: Vec::new(),
            });
        }

        // Metadata cache: name -> Arc<PackageMetadata>
        let mut metadata_cache: HashMap<String, Arc<PackageMetadata>> = HashMap::new();

        // ----- Phase 1: pre-fetch root package metadata in parallel ---------
        // Collect package names to fetch, resolving npm: aliases to real names
        let mut root_names: Vec<String> = Vec::new();
        for (name, range) in root_deps {
            let spec = DependencySpec::parse(range);
            if let DependencySpec::Alias { ref real_name, .. } = spec {
                root_names.push(real_name.clone());
            } else {
                root_names.push(name.clone());
            }
        }
        let batch_results = self.registry.fetch_metadata_batch(root_names).await;
        for (name, result) in batch_results {
            match result {
                Ok(meta) => {
                    metadata_cache.insert(name, Arc::new(meta));
                }
                Err(e) => {
                    debug!("Failed to prefetch metadata for '{}': {}", name, e);
                }
            }
        }

        // ----- Phase 2: greedy BFS resolution (batch-drain) -----------------
        // resolved: name -> list of (version_string, ResolvedPackage)
        // Supports multiple versions of the same package when ranges conflict.
        let mut resolved: HashMap<String, Vec<(String, ResolvedPackage)>> = HashMap::new();

        // BFS queue
        let mut queue: VecDeque<QueueEntry> = VecDeque::new();

        // Track which peer dependencies have been auto-installed to avoid re-adding them
        let mut auto_installed_peers: std::collections::HashSet<String> =
            std::collections::HashSet::new();

        // Seed the queue with root dependencies.
        for (name, range) in root_deps {
            queue.push_back(QueueEntry {
                name: name.clone(),
                range: range.clone(),
                optional: false,
            });
        }

        const BATCH_SIZE: usize = 32;

        while !queue.is_empty() {
            // Drain up to BATCH_SIZE entries from the queue
            let batch: Vec<QueueEntry> = queue.drain(..queue.len().min(BATCH_SIZE)).collect();

            // Collect names that need metadata fetching.
            // For npm: alias deps, fetch the *real* package name.
            let missing_names: Vec<String> = batch
                .iter()
                .filter(|entry| !has_satisfying_version(&resolved, &entry.name, &entry.range))
                .map(|entry| {
                    let spec = DependencySpec::parse(&entry.range);
                    if let DependencySpec::Alias { ref real_name, .. } = spec {
                        real_name.clone()
                    } else {
                        entry.name.clone()
                    }
                })
                .filter(|name| !metadata_cache.contains_key(name))
                .collect::<std::collections::HashSet<_>>()
                .into_iter()
                .collect();

            // Fetch all missing metadata concurrently
            if !missing_names.is_empty() {
                let batch_results = self.registry.fetch_metadata_batch(missing_names).await;
                for (name, result) in batch_results {
                    match result {
                        Ok(meta) => {
                            metadata_cache.insert(name, Arc::new(meta));
                        }
                        Err(e) => {
                            debug!("Failed to fetch metadata for '{}': {}", name, e);
                            // Will be handled per-entry below
                        }
                    }
                }
            }

            // Process each entry in the batch
            for entry in batch {
                // -- Check if already resolved and compatible -----------------
                if let Some(versions) = resolved.get(&entry.name) {
                    // Check if any existing version satisfies the requested range
                    let any_satisfies = versions
                        .iter()
                        .any(|(ver, _)| version_satisfies(ver, &entry.range));
                    if any_satisfies {
                        trace!(
                            "{} already has a version satisfying '{}'",
                            entry.name,
                            entry.range
                        );
                        continue;
                    }
                    // No existing version satisfies — fall through to resolve a new one
                    debug!(
                        "Resolving additional version of '{}' for range '{}' (existing: {})",
                        entry.name,
                        entry.range,
                        versions
                            .iter()
                            .map(|(v, _)| v.as_str())
                            .collect::<Vec<_>>()
                            .join(", ")
                    );
                }

                // -- Check workspace packages -----------------------------------
                if let Some((ws_version, ws_path)) = self.workspace_packages.get(&entry.name) {
                    let spec = DependencySpec::parse(&entry.range);
                    let is_ws_dep = matches!(spec, DependencySpec::Workspace { .. })
                        || self.workspace_packages.contains_key(&entry.name);

                    if is_ws_dep {
                        // Validate version satisfies range if specified
                        if let DependencySpec::Workspace { ref range } = spec {
                            if range != "*" && !range.is_empty() {
                                // For ^ or ~ prefixes, build a semver range from ws version
                                let effective_range = if range == "^" {
                                    format!("^{}", ws_version)
                                } else if range == "~" {
                                    format!("~{}", ws_version)
                                } else {
                                    range.clone()
                                };
                                if !version_satisfies(ws_version, &effective_range) {
                                    warn!(
                                        "Workspace package '{}@{}' does not satisfy range '{}'",
                                        entry.name, ws_version, effective_range
                                    );
                                }
                            }
                        }

                        let relative_path = ws_path.to_string_lossy().replace('\\', "/");
                        let pkg = ResolvedPackage {
                            name: entry.name.clone(),
                            version: format!("workspace:{}", relative_path),
                            tarball_url: String::new(),
                            integrity: String::new(),
                            dependencies: Vec::new(),
                            peer_dependencies: Vec::new(),
                            bin: HashMap::new(),
                            has_install_script: false,
                        };
                        resolved
                            .entry(entry.name.clone())
                            .or_default()
                            .push((pkg.version.clone(), pkg));
                        continue;
                    }
                }

                // -- Check if this is a non-semver spec ----------------------
                let spec = DependencySpec::parse(&entry.range);
                if !spec.is_semver() {
                    match &spec {
                        DependencySpec::Alias { real_name, range } => {
                            // npm: alias — fetch metadata for the real package,
                            // resolve version, but store under the alias name.
                            let alias_meta = match metadata_cache.get(real_name) {
                                Some(m) => Arc::clone(m),
                                None => {
                                    match self.registry.fetch_package_metadata(real_name).await {
                                        Ok(m) => {
                                            let arc = Arc::new(m);
                                            metadata_cache
                                                .insert(real_name.clone(), Arc::clone(&arc));
                                            arc
                                        }
                                        Err(e) => {
                                            if entry.optional {
                                                debug!(
                                                    "Skipping optional alias dep '{}': {}",
                                                    entry.name, e
                                                );
                                                continue;
                                            }
                                            return Err(e);
                                        }
                                    }
                                }
                            };

                            let override_ver = self.overrides.get(&entry.name).map(|s| s.as_str());
                            let (version, version_meta) =
                                match find_best_version(&alias_meta, range, override_ver) {
                                    Ok(v) => v,
                                    Err(e) => {
                                        if entry.optional {
                                            debug!(
                                                "Skipping optional alias dep '{}': {}",
                                                entry.name, e
                                            );
                                            continue;
                                        }
                                        return Err(e);
                                    }
                                };

                            if !is_platform_compatible(version_meta) {
                                debug!(
                                    "Skipping {}@{}: incompatible platform",
                                    entry.name, version
                                );
                                continue;
                            }

                            debug!("Resolved alias {} → {}@{}", entry.name, real_name, version);

                            // Apply readPackage hook
                            let (hooked_deps, hooked_opt_deps, hooked_peers) = self
                                .apply_read_package_hook(
                                    real_name,
                                    &version,
                                    &version_meta.dependencies,
                                    &version_meta.optional_dependencies,
                                    &version_meta.peer_dependencies,
                                );

                            let mut dep_refs: Vec<String> = Vec::new();
                            let mut peer_dep_refs: Vec<String> = Vec::new();

                            if let Some(ref deps) = hooked_deps {
                                for (dep_name, dep_range) in deps {
                                    dep_refs.push(format!("{}@{}", dep_name, dep_range));
                                    if !has_satisfying_version(&resolved, dep_name, dep_range) {
                                        queue.push_back(QueueEntry {
                                            name: dep_name.clone(),
                                            range: dep_range.clone(),
                                            optional: false,
                                        });
                                    }
                                }
                            }

                            if let Some(ref opt_deps) = hooked_opt_deps {
                                for (dep_name, dep_range) in opt_deps {
                                    dep_refs.push(format!("{}@{}", dep_name, dep_range));
                                    if !has_satisfying_version(&resolved, dep_name, dep_range) {
                                        queue.push_back(QueueEntry {
                                            name: dep_name.clone(),
                                            range: dep_range.clone(),
                                            optional: true,
                                        });
                                    }
                                }
                            }

                            if let Some(ref peers) = hooked_peers {
                                for (dep_name, dep_range) in peers {
                                    peer_dep_refs.push(format!("{}@{}", dep_name, dep_range));

                                    if self.auto_install_peers {
                                        let peer_key = format!("{}@{}", dep_name, dep_range);

                                        if !has_satisfying_version(&resolved, dep_name, dep_range)
                                            && !auto_installed_peers.contains(&peer_key)
                                        {
                                            debug!(
                                                "Auto-installing peer dependency: {} requires {}",
                                                entry.name, peer_key
                                            );
                                            queue.push_back(QueueEntry {
                                                name: dep_name.clone(),
                                                range: dep_range.clone(),
                                                optional: false,
                                            });
                                            auto_installed_peers.insert(peer_key);
                                        }
                                    }
                                }
                            }

                            let pkg = ResolvedPackage {
                                name: entry.name.clone(),
                                version: version.clone(),
                                tarball_url: version_meta.dist.tarball.clone(),
                                integrity: integrity_string(&version_meta.dist),
                                dependencies: dep_refs,
                                peer_dependencies: peer_dep_refs,
                                bin: extract_bin(&version_meta.bin, &entry.name),
                                has_install_script: version_meta
                                    .has_install_script
                                    .unwrap_or(false),
                            };

                            resolved
                                .entry(entry.name.clone())
                                .or_default()
                                .push((version, pkg));
                            continue;
                        }
                        DependencySpec::Workspace { .. } => {
                            // Workspace dep but the target is not in workspace_packages.
                            // This can happen if the workspace member isn't found.
                            warn!(
                                "Workspace dependency '{}' not found in workspace members",
                                entry.name
                            );
                            continue;
                        }
                        DependencySpec::Catalog { .. } => {
                            // Catalog deps should be pre-resolved before calling resolve().
                            warn!(
                                "Unresolved catalog dependency '{}': catalog refs must be resolved before resolution",
                                entry.name
                            );
                            continue;
                        }
                        DependencySpec::Link { path } => {
                            debug!(
                                "Link dependency '{}' -> {} (will be symlinked by linker)",
                                entry.name, path
                            );
                            let pkg = ResolvedPackage {
                                name: entry.name.clone(),
                                version: format!("link:{}", path),
                                tarball_url: String::new(),
                                integrity: String::new(),
                                dependencies: Vec::new(),
                                peer_dependencies: Vec::new(),
                                bin: HashMap::new(),
                                has_install_script: false,
                            };
                            resolved
                                .entry(entry.name.clone())
                                .or_default()
                                .push((pkg.version.clone(), pkg));
                            continue;
                        }
                        DependencySpec::File { path } => {
                            debug!("File dependency '{}' -> {}", entry.name, path);
                            // Read package.json from the file path to extract transitive deps
                            let mut dep_refs: Vec<String> = Vec::new();
                            let file_path = std::path::Path::new(&path);
                            let pkg_json_path = file_path.join("package.json");
                            let mut has_scripts = false;
                            let mut file_bin = HashMap::new();
                            if let Ok(content) = std::fs::read_to_string(&pkg_json_path) {
                                if let Ok(json) =
                                    serde_json::from_str::<serde_json::Value>(&content)
                                {
                                    // Extract dependencies and enqueue them
                                    if let Some(deps) =
                                        json.get("dependencies").and_then(|d| d.as_object())
                                    {
                                        for (dep_name, dep_range) in deps {
                                            if let Some(range) = dep_range.as_str() {
                                                dep_refs.push(format!("{}@{}", dep_name, range));
                                                if !has_satisfying_version(
                                                    &resolved, dep_name, range,
                                                ) {
                                                    queue.push_back(QueueEntry {
                                                        name: dep_name.clone(),
                                                        range: range.to_string(),
                                                        optional: false,
                                                    });
                                                }
                                            }
                                        }
                                    }
                                    // Check for install scripts
                                    if let Some(scripts) =
                                        json.get("scripts").and_then(|s| s.as_object())
                                    {
                                        has_scripts = scripts.contains_key("preinstall")
                                            || scripts.contains_key("install")
                                            || scripts.contains_key("postinstall");
                                    }
                                    // Extract bin
                                    file_bin = extract_bin(&json.get("bin").cloned(), &entry.name);
                                }
                            }
                            let pkg = ResolvedPackage {
                                name: entry.name.clone(),
                                version: format!("file:{}", path),
                                tarball_url: String::new(),
                                integrity: String::new(),
                                dependencies: dep_refs,
                                peer_dependencies: Vec::new(),
                                bin: file_bin,
                                has_install_script: has_scripts,
                            };
                            resolved
                                .entry(entry.name.clone())
                                .or_default()
                                .push((pkg.version.clone(), pkg));
                            continue;
                        }
                        DependencySpec::Git { url, reference } => {
                            debug!(
                                "Git dependency '{}' -> {}#{}",
                                entry.name,
                                url,
                                reference.as_deref().unwrap_or("HEAD")
                            );
                            let version =
                                format!("git+{}#{}", url, reference.as_deref().unwrap_or("HEAD"));
                            let pkg = ResolvedPackage {
                                name: entry.name.clone(),
                                version: version.clone(),
                                tarball_url: String::new(),
                                integrity: String::new(),
                                dependencies: Vec::new(),
                                peer_dependencies: Vec::new(),
                                bin: HashMap::new(),
                                has_install_script: false,
                            };
                            resolved
                                .entry(entry.name.clone())
                                .or_default()
                                .push((version, pkg));
                            continue;
                        }
                        DependencySpec::Github {
                            user,
                            repo,
                            reference,
                        } => {
                            debug!(
                                "GitHub dependency '{}' -> {}/{}#{}",
                                entry.name,
                                user,
                                repo,
                                reference.as_deref().unwrap_or("HEAD")
                            );
                            let version = format!(
                                "github:{}/{}#{}",
                                user,
                                repo,
                                reference.as_deref().unwrap_or("HEAD")
                            );
                            let pkg = ResolvedPackage {
                                name: entry.name.clone(),
                                version: version.clone(),
                                tarball_url: format!(
                                    "https://codeload.github.com/{}/{}/tar.gz/{}",
                                    user,
                                    repo,
                                    reference.as_deref().unwrap_or("HEAD")
                                ),
                                integrity: String::new(),
                                dependencies: Vec::new(),
                                peer_dependencies: Vec::new(),
                                bin: HashMap::new(),
                                has_install_script: false,
                            };
                            resolved
                                .entry(entry.name.clone())
                                .or_default()
                                .push((version, pkg));
                            continue;
                        }
                        _ => {} // Semver handled below
                    }
                }

                // -- Get metadata (from cache or single fetch) ----------------
                let metadata = match metadata_cache.get(&entry.name) {
                    Some(m) => Arc::clone(m),
                    None => {
                        // Batch fetch missed this one — try individual fetch
                        match self.registry.fetch_package_metadata(&entry.name).await {
                            Ok(m) => {
                                let arc = Arc::new(m);
                                metadata_cache.insert(entry.name.clone(), Arc::clone(&arc));
                                arc
                            }
                            Err(e) => {
                                if entry.optional {
                                    debug!("Skipping optional dependency '{}': {}", entry.name, e);
                                    continue;
                                }
                                return Err(e);
                            }
                        }
                    }
                };

                // -- Pick the best version ------------------------------------
                let override_ver = self.overrides.get(&entry.name).map(|s| s.as_str());
                let (version, version_meta) =
                    match find_best_version(&metadata, &entry.range, override_ver) {
                        Ok(v) => v,
                        Err(e) => {
                            if entry.optional {
                                debug!("Skipping optional dependency '{}': {}", entry.name, e);
                                continue;
                            }
                            return Err(e);
                        }
                    };

                // -- Platform check -----------------------------------------------
                if !is_platform_compatible(version_meta) {
                    debug!(
                        "Skipping {}@{}: incompatible with current platform (os={}, cpu={})",
                        entry.name,
                        version,
                        current_os(),
                        current_cpu()
                    );
                    continue;
                }

                debug!("Resolved {}@{}", entry.name, version);

                // -- Apply readPackage hook ------------------------------------
                let (hooked_deps, hooked_opt_deps, hooked_peers) = self.apply_read_package_hook(
                    &entry.name,
                    &version,
                    &version_meta.dependencies,
                    &version_meta.optional_dependencies,
                    &version_meta.peer_dependencies,
                );

                // -- Collect dependency refs & enqueue transitive deps ---------
                let mut dep_refs: Vec<String> = Vec::new();
                let mut peer_dep_refs: Vec<String> = Vec::new();

                if let Some(ref deps) = hooked_deps {
                    for (dep_name, dep_range) in deps {
                        dep_refs.push(format!("{}@{}", dep_name, dep_range));
                        if !has_satisfying_version(&resolved, dep_name, dep_range) {
                            queue.push_back(QueueEntry {
                                name: dep_name.clone(),
                                range: dep_range.clone(),
                                optional: false,
                            });
                        }
                    }
                }

                // Optional dependencies
                if let Some(ref opt_deps) = hooked_opt_deps {
                    for (dep_name, dep_range) in opt_deps {
                        dep_refs.push(format!("{}@{}", dep_name, dep_range));
                        if !has_satisfying_version(&resolved, dep_name, dep_range) {
                            queue.push_back(QueueEntry {
                                name: dep_name.clone(),
                                range: dep_range.clone(),
                                optional: true,
                            });
                        }
                    }
                }

                // Peer dependencies — collect and optionally auto-install
                if let Some(ref peers) = hooked_peers {
                    for (dep_name, dep_range) in peers {
                        peer_dep_refs.push(format!("{}@{}", dep_name, dep_range));

                        if self.auto_install_peers {
                            let peer_key = format!("{}@{}", dep_name, dep_range);

                            if !has_satisfying_version(&resolved, dep_name, dep_range)
                                && !auto_installed_peers.contains(&peer_key)
                            {
                                debug!(
                                    "Auto-installing peer dependency: {} requires {}",
                                    entry.name, peer_key
                                );
                                queue.push_back(QueueEntry {
                                    name: dep_name.clone(),
                                    range: dep_range.clone(),
                                    optional: false,
                                });
                                auto_installed_peers.insert(peer_key);
                            }
                        }
                    }
                }

                // Build the resolved package record.
                let pkg = ResolvedPackage {
                    name: entry.name.clone(),
                    version: version.clone(),
                    tarball_url: version_meta.dist.tarball.clone(),
                    integrity: integrity_string(&version_meta.dist),
                    dependencies: dep_refs,
                    peer_dependencies: peer_dep_refs,
                    bin: extract_bin(&version_meta.bin, &entry.name),
                    has_install_script: version_meta.has_install_script.unwrap_or(false),
                };

                resolved
                    .entry(entry.name.clone())
                    .or_default()
                    .push((version, pkg));
            }
        }

        // ----- Phase 3: fixup dependency refs with resolved versions ---------
        // Build a lookup: name -> list of resolved versions
        let resolved_versions: HashMap<String, Vec<String>> = resolved
            .iter()
            .map(|(name, versions)| {
                (
                    name.clone(),
                    versions.iter().map(|(ver, _)| ver.clone()).collect(),
                )
            })
            .collect();

        // Flatten all versions into a single list of packages
        let packages: Vec<ResolvedPackage> = resolved
            .into_values()
            .flat_map(|versions| versions.into_iter().map(|(_, pkg)| pkg))
            .map(|mut pkg| {
                pkg.dependencies = pkg
                    .dependencies
                    .iter()
                    .filter_map(|dep_ref| {
                        let (dep_name, dep_range) = split_dep_ref(dep_ref);
                        find_best_resolved_version(&resolved_versions, dep_name, dep_range)
                            .map(|ver| format!("{}@{}", dep_name, ver))
                    })
                    .collect();
                // Fixup peer dep refs too
                pkg.peer_dependencies = pkg
                    .peer_dependencies
                    .iter()
                    .filter_map(|dep_ref| {
                        let (dep_name, dep_range) = split_dep_ref(dep_ref);
                        find_best_resolved_version(&resolved_versions, dep_name, dep_range)
                            .map(|ver| format!("{}@{}", dep_name, ver))
                    })
                    .collect();
                pkg
            })
            .collect();

        // ----- Phase 4: validate peer dependencies ---------------------------
        // Only warn about unmet peers if auto_install_peers is disabled.
        // When auto_install_peers is enabled, all non-optional peers should have been queued.
        if !self.auto_install_peers {
            let pkg_map: HashMap<&str, &ResolvedPackage> =
                packages.iter().map(|p| (p.name.as_str(), p)).collect();
            for pkg in &packages {
                if pkg.peer_dependencies.is_empty() {
                    continue;
                }
                for peer_ref in &pkg.peer_dependencies {
                    let (peer_name, _) = split_dep_ref(peer_ref);
                    if !pkg_map.contains_key(peer_name) {
                        warn!(
                            "Unmet peer dependency: '{}' requires peer '{}' but it is not installed.",
                            pkg.name, peer_ref
                        );
                    }
                }
            }
        }

        Ok(DependencyGraph { packages })
    }
}

// ---------------------------------------------------------------------------
// Small utility functions
// ---------------------------------------------------------------------------

/// Split a `"name@range"` reference into `(name, range)`.
///
/// Handles scoped packages correctly: `"@scope/pkg@^1.0"` → `("@scope/pkg", "^1.0")`.
fn split_dep_ref(dep_ref: &str) -> (&str, &str) {
    // If it starts with '@' the first '@' is part of the scope – find the
    // second '@'.
    if let Some(stripped) = dep_ref.strip_prefix('@') {
        if let Some(idx) = stripped.find('@') {
            return (&dep_ref[..idx + 1], &stripped[idx + 1..]);
        }
        // No second '@' – the whole string is the name, range is empty.
        return (dep_ref, "");
    }
    // Non-scoped: first '@' separates name from range.
    if let Some(idx) = dep_ref.find('@') {
        (&dep_ref[..idx], &dep_ref[idx + 1..])
    } else {
        (dep_ref, "")
    }
}

/// Check if the resolved map has any version of `name` that satisfies `range`.
fn has_satisfying_version(
    resolved: &HashMap<String, Vec<(String, ResolvedPackage)>>,
    name: &str,
    range: &str,
) -> bool {
    match resolved.get(name) {
        None => false,
        Some(versions) => versions
            .iter()
            .any(|(ver, _)| version_satisfies(ver, range)),
    }
}

/// Find the best resolved version for a dependency reference.
/// Prefers a version that satisfies the range; falls back to the first version.
fn find_best_resolved_version(
    resolved_versions: &HashMap<String, Vec<String>>,
    name: &str,
    range: &str,
) -> Option<String> {
    resolved_versions.get(name).and_then(|versions| {
        // Try to find a version that satisfies the range
        versions
            .iter()
            .find(|ver| version_satisfies(ver, range))
            .or_else(|| versions.first())
            .cloned()
    })
}

/// Check whether `version_str` satisfies the given semver `range_str`.
fn version_satisfies(version_str: &str, range_str: &str) -> bool {
    let range_str = range_str.trim();

    // Normalise wildcards.
    let effective = match range_str {
        "" | "*" | "latest" => ">=0.0.0",
        s => s,
    };

    let version = match cached_parse_version(version_str) {
        Some(v) => v,
        None => return false,
    };

    let range = match cached_parse_range(effective) {
        Some(r) => r,
        None => return false,
    };

    range.satisfies(&version)
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    /// Build a minimal `PackageMetadata` with the given versions.
    fn make_metadata(name: &str, versions: &[&str]) -> PackageMetadata {
        let mut ver_map = HashMap::new();
        for v in versions {
            ver_map.insert(
                v.to_string(),
                VersionMetadata {
                    name: name.to_string(),
                    version: v.to_string(),
                    dependencies: None,
                    dev_dependencies: None,
                    peer_dependencies: None,
                    optional_dependencies: None,
                    dist: DistInfo {
                        tarball: format!(
                            "https://registry.npmjs.org/{}/-/{}-{}.tgz",
                            name, name, v
                        ),
                        shasum: "abc123".to_string(),
                        integrity: Some("sha512-test".to_string()),
                    },
                    bin: None,
                    os: None,
                    cpu: None,
                    has_install_script: None,
                },
            );
        }
        let latest = versions.last().unwrap_or(&"0.0.0").to_string();
        let mut dist_tags = HashMap::new();
        dist_tags.insert("latest".to_string(), latest);
        PackageMetadata {
            name: name.to_string(),
            versions: ver_map,
            dist_tags,
        }
    }

    #[test]
    fn test_find_best_version_caret() {
        let meta = make_metadata("foo", &["1.0.0", "1.2.3", "1.5.0", "2.0.0"]);
        let (ver, _) = find_best_version(&meta, "^1.2.0", None).unwrap();
        assert_eq!(ver, "1.5.0");
    }

    #[test]
    fn test_find_best_version_tilde() {
        let meta = make_metadata("foo", &["1.0.0", "1.2.3", "1.2.9", "1.3.0"]);
        let (ver, _) = find_best_version(&meta, "~1.2.0", None).unwrap();
        assert_eq!(ver, "1.2.9");
    }

    #[test]
    fn test_find_best_version_wildcard() {
        let meta = make_metadata("foo", &["1.0.0", "2.0.0", "3.0.0"]);
        let (ver, _) = find_best_version(&meta, "*", None).unwrap();
        assert_eq!(ver, "3.0.0");
    }

    #[test]
    fn test_find_best_version_exact() {
        let meta = make_metadata("foo", &["1.0.0", "1.2.3", "2.0.0"]);
        let (ver, _) = find_best_version(&meta, "1.2.3", None).unwrap();
        assert_eq!(ver, "1.2.3");
    }

    #[test]
    fn test_find_best_version_latest_tag() {
        let meta = make_metadata("foo", &["1.0.0", "2.0.0"]);
        let (ver, _) = find_best_version(&meta, "latest", None).unwrap();
        assert_eq!(ver, "2.0.0");
    }

    #[test]
    fn test_find_best_version_no_match() {
        let meta = make_metadata("foo", &["1.0.0", "1.1.0"]);
        let result = find_best_version(&meta, "^2.0.0", None);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_bin_none() {
        let result = extract_bin(&None, "my-pkg");
        assert!(result.is_empty());
    }

    #[test]
    fn test_extract_bin_string() {
        let val = serde_json::Value::String("./bin/cli.js".to_string());
        let result = extract_bin(&Some(val), "my-pkg");
        assert_eq!(result.get("my-pkg").unwrap(), "./bin/cli.js");
    }

    #[test]
    fn test_extract_bin_string_scoped() {
        let val = serde_json::Value::String("./bin/cli.js".to_string());
        let result = extract_bin(&Some(val), "@scope/my-pkg");
        assert_eq!(result.get("my-pkg").unwrap(), "./bin/cli.js");
    }

    #[test]
    fn test_extract_bin_object() {
        let obj = serde_json::json!({
            "cmd1": "./bin/cmd1.js",
            "cmd2": "./bin/cmd2.js"
        });
        let result = extract_bin(&Some(obj), "my-pkg");
        assert_eq!(result.len(), 2);
        assert_eq!(result.get("cmd1").unwrap(), "./bin/cmd1.js");
        assert_eq!(result.get("cmd2").unwrap(), "./bin/cmd2.js");
    }

    #[test]
    fn test_split_dep_ref_simple() {
        let (name, range) = split_dep_ref("react@^18.0.0");
        assert_eq!(name, "react");
        assert_eq!(range, "^18.0.0");
    }

    #[test]
    fn test_split_dep_ref_scoped() {
        let (name, range) = split_dep_ref("@babel/core@^7.0.0");
        assert_eq!(name, "@babel/core");
        assert_eq!(range, "^7.0.0");
    }

    #[test]
    fn test_version_satisfies_basic() {
        assert!(version_satisfies("1.5.0", "^1.2.0"));
        assert!(!version_satisfies("2.0.0", "^1.2.0"));
        assert!(version_satisfies("3.0.0", "*"));
        assert!(version_satisfies("1.0.0", "latest"));
    }
}