lockfile.rs

//! Lockfile — in-memory representation of bun.lock / bun.lockb

use core::cmp::Ordering;
use core::fmt;
use std::io::Write as _;

use bun_alloc::AllocError;
use bun_collections::{
    ArrayHashMap, ArrayIdentityContext, ArrayIdentityContextU64, DynamicBitSet,
    HashMap as BunHashMap, IdentityContext, LinearFifo, linear_fifo::DynamicBuffer,
};
use bun_core::fmt::PathSep;
use bun_core::{Error as BunError, Global, Output, err};
use bun_paths::{MAX_PATH_BYTES, PathBuffer, SEP, SEP_STR, platform, resolve_path};
// `bun_install` sits above `bun_resolver` in the crate graph (no cycle), so use
// the real resolver `FileSystem` directly — same as `PackageManager.rs`.
use crate::bun_json as JSON;
use bun_core::zstr;
use bun_core::{ZStr, strings};
use bun_dotenv as DotEnv;
use bun_perf::system_timer::Timer;
use bun_resolver::fs::{self as Fs, FileSystem};
use bun_semver::{self as Semver, ExternalString, String as SemverString};
use bun_sha_hmac as Crypto;
use bun_sys::{self as sys, Fd, File};

use crate::config_version::ConfigVersion;
use crate::migration;
use crate::package_manager::WorkspaceFilter;
use crate::package_manager_real::{
    Options as PackageManagerOptions, options::LogLevel, populate_manifest_cache,
};
use crate::resolution_real::{self as resolution, Resolution};
use crate::string_builder;
use crate::update_request::UpdateRequest;
use crate::{
    self as Install, DependencyID, ExternalSlice, Features, PackageID, PackageManager,
    PackageNameAndVersionHash, PackageNameHash, TruncatedPackageNameHash, dependency,
    dependency::Dependency, initialize_store, invalid_dependency_id, invalid_package_id,
    npm as Npm,
};

// ────────────────────────────────────────────────────────────────────────────
// Sub-module declarations — explicit #[path] attrs for PascalCase / dotted
// file names.
// ────────────────────────────────────────────────────────────────────────────

#[path = "lockfile/Buffers.rs"]
pub mod buffers;
#[path = "lockfile/bun.lock.rs"]
pub mod bun_lock;
#[path = "lockfile/bun.lockb.rs"]
pub mod bun_lockb;
#[path = "lockfile/CatalogMap.rs"]
pub mod catalog_map;
#[path = "lockfile/lockfile_json_stringify_for_debugging.rs"]
pub mod lockfile_json_stringify_for_debugging;
#[path = "lockfile/OverrideMap.rs"]
pub mod override_map;
#[path = "lockfile/Package.rs"]
pub mod package;
#[path = "lockfile/Tree.rs"]
pub mod tree;
#[path = "lockfile/printer"]
pub mod printer_mods {
    #[path = "tree_printer.rs"]
    pub mod tree_printer;
    #[path = "Yarn.rs"]
    pub mod yarn;
}

// Sub-module re-exports
pub use self::buffers::Buffers;
use self::bun_lock as TextLockfile;
pub use self::bun_lockb as Serializer;
pub use self::catalog_map::CatalogMap;
pub use self::lockfile_json_stringify_for_debugging::json_stringify;
pub use self::override_map::OverrideMap;
pub use self::package::Package;
pub use self::tree::Tree;
pub use crate::padding_checker::assert_no_uninitialized_padding;
// Bring the derive-generated `items_*` column accessors (`PackageColumns` for
// `MultiArrayList<Package>`, `PackageColumns` for `Slice<Package>`) into scope.
use self::package::PackageColumns as _;

// Local aliases for module-level types.
type DependencyVersion = dependency::Version;
type ResolutionTag = resolution::Tag;
type SemverStringBuf<'a> = bun_semver::semver_string::Buf<'a>;
type SemverStringBuilder = bun_semver::semver_string::Builder;

// ────────────────────────────────────────────────────────────────────────────
// Type aliases / collection types
// ────────────────────────────────────────────────────────────────────────────

pub(crate) type PackageIDSlice = ExternalSlice<PackageID>;
pub type DependencySlice = ExternalSlice<Dependency>;
pub(crate) type DependencyIDSlice = ExternalSlice<DependencyID>;

pub(crate) type PackageIDList = Vec<PackageID>;
pub(crate) type DependencyList = Vec<Dependency>;
pub(crate) type DependencyIDList = Vec<DependencyID>;

pub(crate) type StringBuffer = Vec<u8>;
pub(crate) type ExternalStringBuffer = Vec<ExternalString>;

pub(crate) type NameHashMap = ArrayHashMap<PackageNameHash, SemverString, ArrayIdentityContextU64>;
/// Value is the exact byte string the key hash was computed from; lookups must
/// compare it since truncated hashes can collide. An empty value is the legacy
/// `bun.lockb` sentinel ("name unknown, hash-only match").
pub(crate) type TrustedDependenciesSet =
    ArrayHashMap<TruncatedPackageNameHash, Box<[u8]>, ArrayIdentityContext>;
pub(crate) type VersionHashMap =
    ArrayHashMap<PackageNameHash, Semver::Version, ArrayIdentityContextU64>;
pub(crate) type PatchedDependenciesMap =
    ArrayHashMap<PackageNameAndVersionHash, PatchedDep, ArrayIdentityContextU64>;

pub(crate) type StringPool = bun_semver::string::StringPool;

pub(crate) type MetaHash = [u8; 32]; // Sha512T256.digest_length
pub(crate) const ZERO_HASH: MetaHash = [0u8; 32];

/// Result of `maybe_clone_filtering_root_packages`: either the input lockfile was
/// returned unchanged (borrowed), or a freshly-allocated cleaned lockfile is returned
/// (owned), so the caller can drop the `Box` when done.
pub enum Cleaned<'a> {
    /// No changes needed — caller's lockfile is returned as-is.
    Same(&'a mut Lockfile),
    /// A new lockfile was allocated by `clean`; caller owns it.
    New(Box<Lockfile>),
}

// The stream owns its backing `Vec<u8>` — every load path hands the file
// contents to the stream anyway,
// which avoids threading a `&mut [u8]` lifetime through the load call graph.
pub type Stream = bun_io::FixedBufferStream<Vec<u8>>;

/// Duck-typed surface that `Buffers::write_array`/`save` and
/// `Package::Serializer::save` expect of their `stream` parameter. Expressed
/// as a trait to stay generic over the borrowck-reshaped `StreamType` in
/// `bun.lockb.rs` (which collapses stream + writer into one `&mut`).
pub trait PositionalStream {
    /// Current write position.
    fn get_pos(&self) -> Result<usize, BunError>;
    /// Positional write — returns bytes written (always `data.len()` for
    /// in-memory buffers).
    fn pwrite(&mut self, data: &[u8], index: usize) -> usize;
}

impl<'a> PositionalStream for Serializer::StreamType<'a> {
    #[inline]
    fn get_pos(&self) -> Result<usize, BunError> {
        Serializer::StreamType::get_pos(self)
    }
    #[inline]
    fn pwrite(&mut self, data: &[u8], index: usize) -> usize {
        Serializer::StreamType::pwrite(self, data, index)
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Lockfile struct
// ────────────────────────────────────────────────────────────────────────────

pub struct Lockfile {
    /// The version of the lockfile format, intended to prevent data corruption for format changes.
    pub format: FormatVersion,

    pub text_lockfile_version: bun_lock::Version,

    pub meta_hash: MetaHash,

    pub packages: PackageList,
    pub buffers: Buffers,

    /// name -> PackageID || [*]PackageID
    /// Not for iterating.
    pub package_index: PackageIndexMap,
    pub string_pool: StringPool,
    pub scratch: Scratch,

    pub scripts: Scripts,
    pub workspace_paths: NameHashMap,
    pub workspace_versions: VersionHashMap,

    /// Optional because `trustedDependencies` in package.json might be an
    /// empty list or it might not exist
    pub trusted_dependencies: Option<TrustedDependenciesSet>,
    pub patched_dependencies: PatchedDependenciesMap,
    pub overrides: OverrideMap,
    pub catalogs: CatalogMap,

    pub saved_config_version: Option<ConfigVersion>,

    /// `packages.len()` at the moment lockfile load (including npm/pnpm/yarn
    /// migration) finished. Packages with `id < this` were carried in from a
    /// lockfile and represent a user-pinned resolution; packages with
    /// `id >= this` were appended by manifest fetches in the current
    /// resolve session. `get_package_id` uses this to keep its
    /// order-independence guard from overriding lockfile pins. Set by
    /// `mark_loaded_packages`; defaults to `invalid_package_id` (no lockfile
    /// loaded → guard applies to nothing, equivalent to "all entries are
    /// session-appended").
    ///
    /// Runtime-only — never serialised.
    pub loaded_package_count: PackageID,

    /// `bit[id] == true` ⇔ package `id` was appended for a dependency whose
    /// version range was an exact `=X.Y.Z` (i.e. the user — root or workspace
    /// — pinned this exact version somewhere in the tree). `get_package_id`'s
    /// order-independence guard never blocks deduping to one of these: an
    /// exact pin is a deliberate choice, not an artifact of which manifest
    /// happened to land first. Runtime-only — never serialised; sized lazily
    /// in `mark_exact_pin`.
    pub exact_pinned: DynamicBitSet,
}

pub(crate) type PackageList = self::package::List<u64>;

// ────────────────────────────────────────────────────────────────────────────
// DepSorter
// ────────────────────────────────────────────────────────────────────────────

pub(crate) struct DepSorter<'a> {
    pub lockfile: &'a Lockfile,
}

impl<'a> DepSorter<'a> {
    pub(crate) fn is_less_than(&self, l: DependencyID, r: DependencyID) -> bool {
        let deps_buf = self.lockfile.buffers.dependencies.as_slice();
        let string_buf = self.lockfile.buffers.string_bytes.as_slice();

        let l_dep = &deps_buf[l as usize];
        let r_dep = &deps_buf[r as usize];

        match l_dep.behavior.cmp(r_dep.behavior) {
            Ordering::Less => true,
            Ordering::Greater => false,
            Ordering::Equal => {
                strings::order(l_dep.name.slice(string_buf), r_dep.name.slice(string_buf))
                    == Ordering::Less
            }
        }
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Scripts
// ────────────────────────────────────────────────────────────────────────────

#[derive(Default)]
pub struct Scripts {
    pub preinstall: Vec<Box<[u8]>>,
    pub install: Vec<Box<[u8]>>,
    pub postinstall: Vec<Box<[u8]>>,
    pub preprepare: Vec<Box<[u8]>>,
    pub prepare: Vec<Box<[u8]>>,
    pub postprepare: Vec<Box<[u8]>>,
}

impl Scripts {
    pub const NAMES: [&'static str; 6] = [
        "preinstall",
        "install",
        "postinstall",
        "preprepare",
        "prepare",
        "postprepare",
    ];

    /// Indexed mutable access matching `NAMES` order.
    pub fn hook_mut(&mut self, i: usize) -> &mut Vec<Box<[u8]>> {
        match i {
            0 => &mut self.preinstall,
            1 => &mut self.install,
            2 => &mut self.postinstall,
            3 => &mut self.preprepare,
            4 => &mut self.prepare,
            5 => &mut self.postprepare,
            _ => unreachable!(),
        }
    }

    /// (name, &entries) in `NAMES` order — single source of truth for the name half.
    /// The field-ref half stays hand-listed (no field-by-name reflection),
    /// but the string half is derived from `NAMES` so the literals exist exactly once.
    fn fields(&self) -> [(&'static str, &Vec<Box<[u8]>>); 6] {
        [
            (Self::NAMES[0], &self.preinstall),
            (Self::NAMES[1], &self.install),
            (Self::NAMES[2], &self.postinstall),
            (Self::NAMES[3], &self.preprepare),
            (Self::NAMES[4], &self.prepare),
            (Self::NAMES[5], &self.postprepare),
        ]
    }

    pub fn has_any(&self) -> bool {
        for (_, list) in self.fields() {
            if !list.is_empty() {
                return true;
            }
        }
        false
    }

    pub fn count(&self) -> usize {
        let mut res: usize = 0;
        for (_, list) in self.fields() {
            res += list.len();
        }
        res
    }
}

// `deinit` becomes `Drop` — body only frees owned fields → delete entirely; Vec<Box<[u8]>> drops automatically.

// ────────────────────────────────────────────────────────────────────────────
// LoadResult
// ────────────────────────────────────────────────────────────────────────────

#[derive(Clone, Copy, PartialEq, Eq)]
pub enum LockfileFormat {
    Text,
    Binary,
}

impl LockfileFormat {
    pub fn filename(self) -> &'static ZStr {
        match self {
            LockfileFormat::Text => zstr!("bun.lock"),
            LockfileFormat::Binary => zstr!("bun.lockb"),
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq)]
pub enum LoadStep {
    OpenFile,
    ReadFile,
    ParseFile,
    Migrating,
}

#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum Migrated {
    #[default]
    None,
    Npm,
    Yarn,
    Pnpm,
}

pub struct LoadResultErr {
    pub step: LoadStep,
    pub value: BunError,
    pub lockfile_path: &'static ZStr,
    pub format: LockfileFormat,
}

pub struct LoadResultOk<'a> {
    pub lockfile: &'a mut Lockfile,
    pub loaded_from_binary_lockfile: bool,
    pub migrated: Migrated,
    pub serializer_result: Serializer::SerializerLoadResult,
    pub format: LockfileFormat,
}

pub enum LoadResult<'a> {
    NotFound,
    Err(LoadResultErr),
    Ok(LoadResultOk<'a>),
}

impl<'a> LoadResult<'a> {
    pub fn loaded_from_text_lockfile(&self) -> bool {
        match self {
            LoadResult::NotFound => false,
            LoadResult::Err(err) => err.format == LockfileFormat::Text,
            LoadResult::Ok(ok) => ok.format == LockfileFormat::Text,
        }
    }

    pub fn loaded_from_binary_lockfile(&self) -> bool {
        match self {
            LoadResult::NotFound => false,
            LoadResult::Err(err) => err.format == LockfileFormat::Binary,
            LoadResult::Ok(ok) => ok.format == LockfileFormat::Binary,
        }
    }

    pub fn migrated_from_npm(&self) -> bool {
        match self {
            LoadResult::Ok(ok) => ok.migrated == Migrated::Npm,
            _ => false,
        }
    }

    pub fn save_format(&self, options: &PackageManagerOptions) -> LockfileFormat {
        match self {
            LoadResult::NotFound => {
                // saving a lockfile for a new project. default to text lockfile
                // unless saveTextLockfile is false in bunfig
                let save_text_lockfile = options.save_text_lockfile.unwrap_or(true);
                if save_text_lockfile {
                    LockfileFormat::Text
                } else {
                    LockfileFormat::Binary
                }
            }
            LoadResult::Err(err) => {
                // an error occurred, but we still loaded from an existing lockfile
                if let Some(save_text_lockfile) = options.save_text_lockfile {
                    if save_text_lockfile {
                        return LockfileFormat::Text;
                    }
                }
                err.format
            }
            LoadResult::Ok(ok) => {
                // loaded from an existing lockfile
                if let Some(save_text_lockfile) = options.save_text_lockfile {
                    if save_text_lockfile {
                        return LockfileFormat::Text;
                    }

                    if ok.migrated != Migrated::None {
                        return LockfileFormat::Binary;
                    }
                }

                if ok.migrated != Migrated::None {
                    return LockfileFormat::Text;
                }

                ok.format
            }
        }
    }

    /// configVersion and boolean for if the configVersion previously existed/needs to be saved to lockfile
    pub fn choose_config_version(&self) -> (ConfigVersion, bool) {
        match self {
            LoadResult::NotFound | LoadResult::Err(_) => (ConfigVersion::CURRENT, true),
            LoadResult::Ok(ok) => match ok.migrated {
                Migrated::None => {
                    if let Some(config_version) = ok.lockfile.saved_config_version {
                        return (config_version, false);
                    }

                    // existing bun project without configVersion
                    (ConfigVersion::V0, true)
                }
                Migrated::Pnpm => (ConfigVersion::V1, true),
                Migrated::Npm => (ConfigVersion::V0, true),
                Migrated::Yarn => (ConfigVersion::V0, true),
            },
        }
    }

    // Callers reach this only after `handleLoadLockfileErrors` has exited on
    // the `NotFound`/`Err` arms, so the variant is known-`Ok`.
    bun_core::enum_unwrap!(pub LoadResult, Ok => fn ok / ok_mut -> LoadResultOk<'a>);
}

// ────────────────────────────────────────────────────────────────────────────
// InstallResult
// ────────────────────────────────────────────────────────────────────────────

// ────────────────────────────────────────────────────────────────────────────
// Lockfile impl — load / clone / hoist / etc.
// ────────────────────────────────────────────────────────────────────────────

impl Lockfile {
    pub fn is_empty(&self) -> bool {
        self.packages.len() == 0
            || (self.packages.len() == 1 && self.packages.get(0).resolutions.len == 0)
    }

    pub fn load_from_cwd<'a, const ATTEMPT_LOADING_FROM_OTHER_LOCKFILE: bool>(
        &'a mut self,
        manager: Option<&mut PackageManager>,
        log: &mut bun_ast::Log,
    ) -> LoadResult<'a> {
        self.load_from_dir::<ATTEMPT_LOADING_FROM_OTHER_LOCKFILE>(Fd::cwd(), manager, log)
    }

    pub fn load_from_dir<'a, const ATTEMPT_LOADING_FROM_OTHER_LOCKFILE: bool>(
        &'a mut self,
        dir: Fd,
        mut manager: Option<&mut PackageManager>,
        log: &mut bun_ast::Log,
    ) -> LoadResult<'a> {
        debug_assert!(Fs::INSTANCE_LOADED.load(core::sync::atomic::Ordering::Relaxed));

        let mut lockfile_format = LockfileFormat::Text;
        let file: File = 'file: {
            match File::openat(dir, zstr!("bun.lock"), sys::O::RDONLY, 0) {
                sys::Result::Ok(f) => break 'file f,
                sys::Result::Err(text_open_err) => {
                    if text_open_err.errno != sys::SystemErrno::ENOENT as u16 {
                        return LoadResult::Err(LoadResultErr {
                            step: LoadStep::OpenFile,
                            value: BunError::from(text_open_err),
                            lockfile_path: zstr!("bun.lock"),
                            format: LockfileFormat::Text,
                        });
                    }

                    lockfile_format = LockfileFormat::Binary;

                    match File::openat(dir, zstr!("bun.lockb"), sys::O::RDONLY, 0) {
                        sys::Result::Ok(f) => break 'file f,
                        sys::Result::Err(binary_open_err) => {
                            if binary_open_err.errno != sys::SystemErrno::ENOENT as u16 {
                                return LoadResult::Err(LoadResultErr {
                                    step: LoadStep::OpenFile,
                                    value: BunError::from(binary_open_err),
                                    lockfile_path: zstr!("bun.lockb"),
                                    format: LockfileFormat::Binary,
                                });
                            }

                            if ATTEMPT_LOADING_FROM_OTHER_LOCKFILE {
                                if let Some(pm) = manager {
                                    // The format is carried inside the `LoadResult` itself.
                                    return migration::detect_and_load_other_lockfile(
                                        self, dir, pm, log,
                                    );
                                }
                            }

                            return LoadResult::NotFound;
                        }
                    }
                }
            }
        };

        // `bun_sys::File::read_to_end` returns `Maybe<Vec<u8>>`
        // (fstat-presized, pread-from-0); map the error arm to `.read_file`.
        let buf = match file.read_to_end() {
            Ok(bytes) => bytes,
            Err(e) => {
                return LoadResult::Err(LoadResultErr {
                    step: LoadStep::ReadFile,
                    value: BunError::from(e),
                    lockfile_path: if lockfile_format == LockfileFormat::Text {
                        zstr!("bun.lock")
                    } else {
                        zstr!("bun.lockb")
                    },
                    format: lockfile_format,
                });
            }
        };

        if lockfile_format == LockfileFormat::Text {
            let source = bun_ast::Source::init_path_string(b"bun.lock", buf.as_slice());
            initialize_store();
            let parsed = match JSON::ParsedJson::parse_package_json(&source, log) {
                Ok(j) => j,
                Err(e) => {
                    return LoadResult::Err(LoadResultErr {
                        step: LoadStep::ParseFile,
                        value: e,
                        lockfile_path: zstr!("bun.lock"),
                        format: lockfile_format,
                    });
                }
            };

            if let Err(e) =
                TextLockfile::parse_into_binary_lockfile(self, parsed.root, &source, log, manager)
            {
                if matches!(e, TextLockfile::ParseError::OutOfMemory) {
                    bun_core::out_of_memory();
                }
                return LoadResult::Err(LoadResultErr {
                    step: LoadStep::ParseFile,
                    value: BunError::from(e),
                    lockfile_path: zstr!("bun.lock"),
                    format: lockfile_format,
                });
            }

            bun_core::analytics::Features::text_lockfile_inc();

            return LoadResult::Ok(LoadResultOk {
                lockfile: self,
                serializer_result: Serializer::SerializerLoadResult::default(),
                loaded_from_binary_lockfile: false,
                migrated: Migrated::None,
                format: lockfile_format,
            });
        }

        let mut result = self.load_from_bytes(manager.as_deref_mut(), buf, log);

        // When BUN_DEBUG_TEST_TEXT_LOCKFILE is set, convert
        // the freshly loaded binary lockfile into a text lockfile in memory,
        // then parse it back into a binary lockfile, so the two codepaths
        // cross-check each other in tests.
        if bun_core::env_var::BUN_DEBUG_TEST_TEXT_LOCKFILE
            .get()
            .unwrap_or(false)
        {
            if let (LoadResult::Ok(ok), Some(manager)) = (&mut result, manager) {
                let mut writer_buf: Vec<u8> = Vec::new();
                // `save_from_binary` reads only `loaded_from_binary_lockfile()`
                // from its `load_result` parameter. `result` itself cannot be
                // passed while `ok.lockfile` is mutably borrowed, so hand it
                // a stand-in that answers
                // `format == Binary` the same way the real `Ok` result does.
                let binary_origin = LoadResult::Err(LoadResultErr {
                    step: LoadStep::ParseFile,
                    value: err!("DebugTextLockfileRoundTrip"),
                    lockfile_path: zstr!("bun.lockb"),
                    format: LockfileFormat::Binary,
                });
                if let Err(e) = TextLockfile::Stringifier::save_from_binary(
                    &mut *ok.lockfile,
                    &binary_origin,
                    &manager.options,
                    &mut writer_buf,
                ) {
                    Output::panic(format_args!(
                        "failed to convert binary lockfile to text lockfile: {}",
                        e.name()
                    ));
                }

                let source = bun_ast::Source::init_path_string(b"bun.lock", writer_buf.as_slice());
                initialize_store();
                let parsed = match JSON::ParsedJson::parse_package_json(&source, log) {
                    Ok(j) => j,
                    Err(e) => Output::panic(format_args!(
                        "failed to print valid json from binary lockfile: {}",
                        e.name()
                    )),
                };

                if let Err(e) = TextLockfile::parse_into_binary_lockfile(
                    &mut *ok.lockfile,
                    parsed.root,
                    &source,
                    log,
                    Some(manager),
                ) {
                    Output::panic(format_args!(
                        "failed to parse text lockfile converted from binary lockfile: {}",
                        <&'static str>::from(e)
                    ));
                }

                bun_core::analytics::Features::text_lockfile_inc();
            }
        }

        result
    }

    pub fn load_from_bytes<'a>(
        &'a mut self,
        pm: Option<&mut PackageManager>,
        buf: Vec<u8>,
        log: &mut bun_ast::Log,
    ) -> LoadResult<'a> {
        let mut stream = Stream::new(buf);

        self.format = FormatVersion::current();
        self.scripts = Scripts::default();
        self.trusted_dependencies = None;
        self.workspace_paths = NameHashMap::default();
        self.workspace_versions = VersionHashMap::default();
        self.overrides = OverrideMap::default();
        self.catalogs = CatalogMap::default();
        self.patched_dependencies = PatchedDependenciesMap::default();

        let load_result = match Serializer::load(self, &mut stream, log, pm) {
            Ok(r) => r,
            Err(e) => {
                return LoadResult::Err(LoadResultErr {
                    step: LoadStep::ParseFile,
                    value: e,
                    lockfile_path: zstr!("bun.lockb"),
                    format: LockfileFormat::Binary,
                });
            }
        };

        if cfg!(debug_assertions) {
            self.verify_data().expect("lockfile data is corrupt");
        }

        LoadResult::Ok(LoadResultOk {
            lockfile: self,
            serializer_result: load_result,
            loaded_from_binary_lockfile: true,
            migrated: Migrated::None,
            format: LockfileFormat::Binary,
        })
    }

    pub fn is_resolved_dependency_disabled(
        &self,
        dep_id: DependencyID,
        features: Features,
        meta: &package::Meta,
        cpu: Npm::Architecture,
        os: Npm::OperatingSystem,
    ) -> bool {
        if meta.is_disabled(cpu, os) {
            return true;
        }

        let dep = &self.buffers.dependencies[dep_id as usize];

        dep.behavior.is_bundled() || !dep.behavior.is_enabled(features)
    }

    /// This conditionally clones the lockfile with root packages marked as non-resolved
    /// that do not satisfy `Features`. The package may still end up installed even
    /// if it was e.g. in "devDependencies" and its a production install. In that case,
    /// it would be installed because another dependency or transient dependency needed it.
    ///
    /// Warning: This potentially modifies the existing lockfile in-place. That is
    /// safe to do because at this stage, the lockfile has already been saved to disk.
    /// Our in-memory representation is all that's left.
    pub fn maybe_clone_filtering_root_packages<'a>(
        old: &'a mut Lockfile,
        manager: &'a mut PackageManager,
        features: Features,
        exact_versions: bool,
        log_level: LogLevel,
    ) -> Result<Cleaned<'a>, BunError> {
        let old_packages = old.packages.slice();
        let old_dependencies_lists = old_packages.items_dependencies();
        let old_resolutions_lists = old_packages.items_resolutions();
        let old_resolutions = old_packages.items_resolution();
        let mut any_changes = false;
        let end: PackageID = old.packages.len() as PackageID;

        // set all disabled dependencies of workspaces to `invalid_package_id`
        for package_id in 0..end as usize {
            if package_id != 0 && old_resolutions[package_id].tag != ResolutionTag::Workspace {
                continue;
            }

            let old_workspace_dependencies_list = old_dependencies_lists[package_id];
            let old_workspace_resolutions_list = old_resolutions_lists[package_id];

            let old_workspace_dependencies =
                old_workspace_dependencies_list.get(old.buffers.dependencies.as_slice());
            let old_workspace_resolutions =
                old_workspace_resolutions_list.mut_(old.buffers.resolutions.as_mut_slice());

            debug_assert_eq!(
                old_workspace_dependencies.len(),
                old_workspace_resolutions.len()
            );
            for (dependency, resolution) in old_workspace_dependencies
                .iter()
                .zip(old_workspace_resolutions.iter_mut())
            {
                if !dependency.behavior.is_enabled(features) && *resolution < end {
                    *resolution = invalid_package_id;
                    any_changes = true;
                }
            }
        }

        if !any_changes {
            return Ok(Cleaned::Same(old));
        }

        old.clean(manager, &mut [], exact_versions, log_level)
            .map(Cleaned::New)
    }

    fn preprocess_update_requests(
        old: &mut Lockfile,
        manager: &mut PackageManager,
        updates: &mut [UpdateRequest],
        exact_versions: bool,
    ) -> Result<(), BunError> {
        let workspace_package_id = manager
            .root_package_id
            .get(old, manager.workspace_name_hash);
        let root_deps_list: DependencySlice =
            old.packages.items_dependencies()[workspace_package_id as usize];

        if (root_deps_list.off as usize) < old.buffers.dependencies.len() {
            // Split-borrow: `string_builder!` only takes
            // `old.buffers.string_bytes` + `old.string_pool`, leaving
            // `old.packages` / `old.buffers.{dependencies,resolutions}` free.
            let mut string_builder = string_builder!(old);

            {
                let root_deps: &[Dependency] =
                    root_deps_list.get(old.buffers.dependencies.as_slice());
                let old_resolutions_list =
                    old.packages.items_resolutions()[workspace_package_id as usize];
                let old_resolutions: &[PackageID] =
                    old_resolutions_list.get(old.buffers.resolutions.as_slice());
                let resolutions_of_yore: &[Resolution] = old.packages.items_resolution();
                let packages_len = old.packages.len();

                for update in updates.iter() {
                    if update.package_id == invalid_package_id {
                        debug_assert_eq!(root_deps.len(), old_resolutions.len());
                        for (dep, &old_resolution) in root_deps.iter().zip(old_resolutions.iter()) {
                            if dep.name_hash == SemverStringBuilder::string_hash(update.name) {
                                if old_resolution as usize >= packages_len {
                                    continue;
                                }
                                let res = resolutions_of_yore[old_resolution as usize];
                                if res.tag != ResolutionTag::Npm
                                    || update.version.tag != dependency::Tag::DistTag
                                {
                                    continue;
                                }

                                // TODO(dylan-conway): this will need to handle updating dependencies (exact, ^, or ~) and aliases

                                let npm_ver = res.npm().version;
                                let len = bun_core::fmt::count(format_args!(
                                    "{}{}",
                                    if exact_versions { "" } else { "^" },
                                    npm_ver.fmt(string_builder.string_bytes.as_slice()),
                                ));

                                if len >= SemverString::MAX_INLINE_LEN {
                                    string_builder.cap += len;
                                }
                            }
                        }
                    }
                }
            }

            string_builder.allocate()?;
            // `string_builder.clamp()` must run once after the entire second
            // loop completes. A scopeguard would mutably capture
            // `string_builder`, conflicting with the `append` calls below. Call `clamp()`
            // explicitly at the end of this block instead (the inner loop has no `?` exits;
            // the only fallible call above is `allocate()`, which precedes this point).

            {
                let mut temp_buf = [0u8; 513];

                let root_deps: &mut [Dependency] =
                    root_deps_list.mut_(old.buffers.dependencies.as_mut_slice());
                let old_resolutions_list_lists = old.packages.items_resolutions();
                let old_resolutions_list =
                    old_resolutions_list_lists[workspace_package_id as usize];
                let old_resolutions: &[PackageID] =
                    old_resolutions_list.get(old.buffers.resolutions.as_slice());
                let resolutions_of_yore: &[Resolution] = old.packages.items_resolution();
                let packages_len = old.packages.len();

                for update in updates.iter_mut() {
                    if update.package_id == invalid_package_id {
                        debug_assert_eq!(root_deps.len(), old_resolutions.len());
                        for (dep, &old_resolution) in
                            root_deps.iter_mut().zip(old_resolutions.iter())
                        {
                            if dep.name_hash == SemverStringBuilder::string_hash(update.name) {
                                if old_resolution as usize >= packages_len {
                                    continue;
                                }
                                let res = resolutions_of_yore[old_resolution as usize];
                                if res.tag != ResolutionTag::Npm
                                    || update.version.tag != dependency::Tag::DistTag
                                {
                                    continue;
                                }

                                // TODO(dylan-conway): this will need to handle updating dependencies (exact, ^, or ~) and aliases

                                let npm_ver = res.npm().version;
                                let buf = {
                                    let mut cursor: &mut [u8] = &mut temp_buf[..];
                                    let start_len = cursor.len();
                                    if write!(
                                        cursor,
                                        "{}{}",
                                        if exact_versions { "" } else { "^" },
                                        npm_ver.fmt(string_builder.string_bytes.as_slice()),
                                    )
                                    .is_err()
                                    {
                                        break;
                                    }
                                    let written = start_len - cursor.len();
                                    &temp_buf[..written]
                                };

                                let external_version = string_builder.append::<ExternalString>(buf);
                                let sliced = external_version
                                    .value
                                    .sliced(string_builder.string_bytes.as_slice());
                                dep.version = dependency::parse(
                                    dep.name,
                                    dep.name_hash,
                                    sliced.slice,
                                    &sliced,
                                    None,
                                    &mut *manager,
                                )
                                .unwrap_or_default();
                            }
                        }
                    }

                    update.e_string = None;
                }
            }

            string_builder.clamp();
        }
        Ok(())
    }

    pub fn clean(
        &mut self,
        manager: &mut PackageManager,
        updates: &mut [UpdateRequest],
        exact_versions: bool,
        log_level: LogLevel,
    ) -> Result<Box<Lockfile>, BunError> {
        // This is wasteful, but we rarely log anything so it's fine.
        let mut log = bun_ast::Log::init();
        // defer { for (...) item.deinit(); log.deinit(); } — handled by Drop

        self.clean_with_logger(manager, updates, &mut log, exact_versions, log_level)
    }

    pub fn resolve_catalog_dependency(&self, dep: &Dependency) -> Option<DependencyVersion> {
        if dep.version.tag != dependency::Tag::Catalog {
            return Some(dep.version.clone());
        }

        let catalog_name = *dep.version.catalog();
        let catalog_dep = self.catalogs.get(self, catalog_name, dep.name)?;

        Some(catalog_dep.version)
    }

    /// Is this a direct dependency of the workspace root package.json?
    pub fn is_workspace_root_dependency(&self, id: DependencyID) -> bool {
        self.packages.items_dependencies()[0].contains(id)
    }

    /// Is this a direct dependency of the workspace the install is taking place in?
    pub fn is_root_dependency(&self, manager: &mut PackageManager, id: DependencyID) -> bool {
        // `RootPackageId::get` caches into `manager`.
        let root_id = manager
            .root_package_id
            .get(self, manager.workspace_name_hash);
        self.packages.items_dependencies()[root_id as usize].contains(id)
    }

    /// Is this a direct dependency of any workspace (including workspace root)?
    /// TODO make this faster by caching the workspace package ids
    pub fn is_workspace_dependency(&self, id: DependencyID) -> bool {
        self.get_workspace_pkg_if_workspace_dep(id) != invalid_package_id
    }

    pub fn get_workspace_pkg_if_workspace_dep(&self, id: DependencyID) -> PackageID {
        let packages = self.packages.slice();
        let resolutions = packages.items_resolution();
        let dependencies_lists = packages.items_dependencies();
        for (pkg_id, (resolution, dependencies)) in resolutions
            .iter()
            .zip(dependencies_lists.iter())
            .enumerate()
        {
            if resolution.tag != ResolutionTag::Workspace && resolution.tag != ResolutionTag::Root {
                continue;
            }
            if dependencies.contains(id) {
                return PackageID::try_from(pkg_id).expect("int cast");
            }
        }

        invalid_package_id
    }

    /// Does this tree id belong to a workspace (including workspace root)?
    /// TODO(dylan-conway) fix!
    pub fn is_workspace_tree_id(&self, id: tree::Id) -> bool {
        id == 0
            || self.buffers.dependencies[self.buffers.trees[id as usize].dependency_id as usize]
                .behavior
                .is_workspace()
    }

    /// Is the package whose `node_modules` this tree represents resolved from a
    /// local `file:` folder? Its `Resolution::Folder` dependencies were normalized
    /// relative to the top-level dir (`Package::parse`), unlike npm's (`Package::from_npm`).
    pub fn is_folder_tree_id(&self, id: tree::Id) -> bool {
        if id == 0 {
            return false;
        }
        let dependency_id = self.buffers.trees[id as usize].dependency_id;
        let package_id = self.buffers.resolutions[dependency_id as usize];
        package_id != invalid_package_id
            && self.packages.slice().items_resolution()[package_id as usize].tag
                == ResolutionTag::Folder
    }

    /// Returns the package id of the workspace the install is taking place in.
    pub fn get_workspace_package_id(
        &self,
        workspace_name_hash: Option<PackageNameHash>,
    ) -> PackageID {
        if let Some(workspace_name_hash_) = workspace_name_hash {
            let packages = self.packages.slice();
            let name_hashes = packages.items_name_hash();
            let resolutions = packages.items_resolution();
            for (i, (res, name_hash)) in resolutions.iter().zip(name_hashes.iter()).enumerate() {
                if res.tag == ResolutionTag::Workspace && *name_hash == workspace_name_hash_ {
                    return PackageID::try_from(i).expect("int cast");
                }
            }

            // should not hit this, default to root just in case
            0
        } else {
            0
        }
    }

    // `#[inline(never)]` keeps the panic/format machinery from
    // `bun_core::output` (pulled in by the cold helpers below) out of callers;
    // the hot copy/remap loop stays in this body while the three cold sections
    // — update-request preprocessing, verbose timer reporting, and the
    // trusted/patched-dependency migration — are outlined so a no-change
    // `bun install` (install/fastify bench) does not page them in.
    #[inline(never)]
    pub fn clean_with_logger(
        &mut self,
        manager: &mut PackageManager,
        updates: &mut [UpdateRequest],
        log: &mut bun_ast::Log,
        exact_versions: bool,
        log_level: LogLevel,
    ) -> Result<Box<Lockfile>, BunError> {
        let old: &mut Lockfile = self;
        // Outlined cold: the verbose arm is debug-only and drags in
        // `Timer`/clock-syscall error formatting.
        let timer: Option<Timer> = if log_level.is_verbose() {
            Some(clean_verbose_timer_start()?)
        } else {
            None
        };

        let old_trusted_dependencies = old.trusted_dependencies.take();
        let old_scripts = core::mem::take(&mut old.scripts);
        // We will only shrink the number of packages here.
        // never grow

        // preinstall_state is used during installPackages. the indexes(package ids) need
        // to be remapped. Also ensure `preinstall_state` has enough capacity to contain
        // all packages. It's possible it doesn't because non-npm packages do not use
        // preinstall state before linking stage.
        manager.ensure_preinstall_state_list_capacity(old.packages.len());
        let preinstall_state = &mut manager.preinstall_state;
        let old_preinstall_state = preinstall_state.clone();
        preinstall_state.fill(Install::PreinstallState::Unknown);

        if !updates.is_empty() {
            clean_preprocess_update_requests_cold(old, manager, updates, exact_versions)?;
        }

        // Caller owns the new lockfile; return `Box<Lockfile>` so Drop reclaims
        // it (never `Box::leak` to satisfy a lifetime).
        let mut new: Box<Lockfile> = Box::default();
        new.string_pool
            .ensure_total_capacity(old.string_pool.capacity())?;
        new.package_index
            .ensure_total_capacity(old.package_index.capacity())?;
        new.packages.ensure_total_capacity(old.packages.len())?;
        new.buffers.preallocate(&old.buffers)?;
        new.patched_dependencies
            .ensure_total_capacity(old.patched_dependencies.count())?;

        // Reset the FIFO read cursor without discarding capacity.
        // `LinearFifo::head` is private; the queue is always drained to empty
        // before reuse here, so a `discard(count)` resets `head` to 0.
        let queued = old.scratch.dependency_list_queue.readable_length();
        old.scratch.dependency_list_queue.discard(queued);

        {
            // The signatures take `&Lockfile` for `old` and read `new`
            // through `builder.lockfile`, so the only conflict left is the
            // field-assign on `new.*` while `builder` borrows `new` — store
            // the results in temps and assign after `builder` drops.
            let old_buf = old.buffers.string_bytes.as_slice();
            let (mut builder, lf) = new.string_builder_split();
            old.overrides.count(old_buf, &mut builder);
            old.catalogs.count(old_buf, &mut builder);
            builder.allocate()?;
            *lf.overrides = old.overrides.clone(manager, old_buf, &mut builder)?;
            *lf.catalogs = old.catalogs.clone(manager, old_buf, &mut builder)?;
        }

        // Step 1. Recreate the lockfile with only the packages that are still alive
        let root = old.root_package().ok_or_else(|| err!("NoPackage"))?;

        let mut package_id_mapping = vec![invalid_package_id; old.packages.len()];
        let clone_queue_ = PendingResolutions::new();
        // Explicit `&mut *` reborrows so `old`/`manager`/`new` are
        // released back to this scope once `cloner` is dropped.
        let mut cloner = Cloner {
            old: &mut *old,
            lockfile: &mut *new,
            mapping: &mut package_id_mapping,
            clone_queue: clone_queue_,
            log,
            old_preinstall_state,
            manager: &mut *manager,
            trees: tree::List::default(),
            trees_count: 1,
        };

        // try clone_queue.ensureUnusedCapacity(root.dependencies.len);
        let _ = root.clone(&mut cloner)?;

        // Between here and `cloner.flush()`, `old`/`new`/`manager`
        // are live inside `cloner`. Reach them via `cloner.old` /
        // `cloner.lockfile` so borrowck sees disjoint field paths.
        {
            let old = &mut *cloner.old;
            let new = &mut *cloner.lockfile;

            // Clone workspace_paths and workspace_versions at the end.
            if old.workspace_paths.count() > 0 || old.workspace_versions.count() > 0 {
                new.workspace_paths
                    .ensure_total_capacity(old.workspace_paths.count())?;
                new.workspace_versions
                    .ensure_total_capacity(old.workspace_versions.count())?;

                // Field-level split borrow of `new` (string_bytes + string_pool).
                let mut workspace_paths_builder = string_builder!(new);

                // Sort by name for determinism
                {
                    let string_buf = old.buffers.string_bytes.as_slice();
                    // `ArrayHashMap::sort` comparator is
                    // `(keys, values, a, b) -> bool` (less-than).
                    old.workspace_paths.sort(|_keys, values, a, b| {
                        let left = values[a];
                        let right = values[b];
                        strings::order(left.slice(string_buf), right.slice(string_buf))
                            == Ordering::Less
                    });
                }

                let old_string_buf = old.buffers.string_bytes.as_slice();
                for path in old.workspace_paths.values() {
                    workspace_paths_builder.count(path.slice(old_string_buf));
                }
                let versions: &[Semver::Version] = old.workspace_versions.values();
                for version in versions {
                    version.count(old_string_buf, &mut workspace_paths_builder);
                }

                workspace_paths_builder.allocate()?;

                // SAFETY: capacity reserved by `ensure_total_capacity` above; every
                // slot in `0..old.count()` is overwritten by the copy/zip loops below
                // before `re_index()` reads them.
                unsafe {
                    new.workspace_paths
                        .set_entries_len(old.workspace_paths.count())
                };

                debug_assert_eq!(
                    old.workspace_paths.values().len(),
                    new.workspace_paths.values().len()
                );
                for (src, dest) in old
                    .workspace_paths
                    .values()
                    .iter()
                    .zip(new.workspace_paths.values_mut().iter_mut())
                {
                    *dest =
                        workspace_paths_builder.append::<SemverString>(src.slice(old_string_buf));
                }
                new.workspace_paths
                    .keys_mut()
                    .copy_from_slice(old.workspace_paths.keys());

                new.workspace_versions
                    .ensure_total_capacity(old.workspace_versions.count())?;
                // SAFETY: capacity reserved immediately above; every slot is filled by
                // the zip loop below before `re_index()`.
                unsafe {
                    new.workspace_versions
                        .set_entries_len(old.workspace_versions.count())
                };
                for (src, dest) in versions
                    .iter()
                    .zip(new.workspace_versions.values_mut().iter_mut())
                {
                    *dest = src.append(old_string_buf, &mut workspace_paths_builder);
                }

                new.workspace_versions
                    .keys_mut()
                    .copy_from_slice(old.workspace_versions.keys());

                workspace_paths_builder.clamp();

                new.workspace_versions.re_index()?;
                new.workspace_paths.re_index()?;
            }
        }

        // When you run `"bun add react"
        // This is where we update it in the lockfile from "latest" to "^17.0.2"
        cloner.flush()?;
        // `cloner` no longer needed — release the reborrows of `old`/`new`/`manager`.
        drop(cloner);

        new.trusted_dependencies = old_trusted_dependencies;
        new.scripts = old_scripts;
        new.meta_hash = old.meta_hash;
        // Carry the on-disk format version over from the lockfile we loaded so a
        // re-save preserves it (a fresh `new` defaults to the current version).
        new.text_lockfile_version = old.text_lockfile_version;

        if old.patched_dependencies.count() > 0 {
            clean_migrate_patched_dependencies_cold(old, &mut new)?;
        }

        // Don't allow invalid memory to happen
        if !updates.is_empty() {
            // `UpdateRequest.version_buf` is a raw `*const [u8]` (PORTING.md
            // type-map: `[]const u8` struct-field, ARENA-class). The slice
            // points into `new.buffers.string_bytes`; `new` is *returned* to
            // the caller below and `string_bytes` is finalized at this point
            // (cloner.flush() and the patched-dep StringBuilder have both
            // run), so the storage outlives every `UpdateRequest` the caller
            // threads it through. No lifetime extension — store the raw
            // (ptr, len) and let `UpdateRequest::version_buf()` reborrow at
            // each read site.
            let string_buf = new.buffers.string_bytes.as_slice();
            let string_buf_ptr = bun_ptr::RawSlice::new(string_buf);
            let slice = new.packages.slice();

            // updates might be applied to the root package.json or one
            // of the workspace package.json files.
            let workspace_package_id = manager
                .root_package_id
                .get(&new, manager.workspace_name_hash);

            let dep_list = slice.items_dependencies()[workspace_package_id as usize];
            let res_list = slice.items_resolutions()[workspace_package_id as usize];
            let workspace_deps: &[Dependency] = dep_list.get(new.buffers.dependencies.as_slice());
            let resolved_ids: &[PackageID] = res_list.get(new.buffers.resolutions.as_slice());

            'request_updated: for update in updates.iter_mut() {
                if update.package_id == invalid_package_id {
                    debug_assert_eq!(resolved_ids.len(), workspace_deps.len());
                    for (&package_id, dep) in resolved_ids.iter().zip(workspace_deps.iter()) {
                        if update.matches(dep, string_buf) {
                            if package_id as usize > new.packages.len() {
                                continue;
                            }
                            update.version_buf = string_buf_ptr;
                            update.version = dep.version.clone();
                            update.package_id = package_id;

                            continue 'request_updated;
                        }
                    }
                }
            }
        }

        if log_level.is_verbose() {
            clean_verbose_report_cold(old, &new, timer.as_ref());
        }

        Ok(new)
    }
}

// ────────────────────────────────────────────────────────────────────────────
// clean_with_logger cold helpers — outlined so the hot copy/remap loop in the
// main body is contiguous in `.text` and the install/fastify no-change bench
// does not fault in update-request rewriting, patched-dep migration, or the
// verbose timer/format machinery.
// ────────────────────────────────────────────────────────────────────────────

#[cold]
#[inline(never)]
fn clean_preprocess_update_requests_cold(
    old: &mut Lockfile,
    manager: &mut PackageManager,
    updates: &mut [UpdateRequest],
    exact_versions: bool,
) -> Result<(), BunError> {
    Lockfile::preprocess_update_requests(old, manager, updates, exact_versions)
}

#[cold]
#[inline(never)]
fn clean_verbose_timer_start() -> Result<Timer, BunError> {
    Timer::start()
}

#[cold]
#[inline(never)]
fn clean_verbose_report_cold(old: &Lockfile, new: &Lockfile, timer: Option<&Timer>) {
    bun_core::pretty_errorln!(
        "Clean lockfile: {} packages -> {} packages in {}\n",
        old.packages.len(),
        new.packages.len(),
        // SAFETY: only entered when `log_level.is_verbose()`, which set `timer = Some(..)`.
        bun_core::fmt::fmt_duration_one_decimal(timer.unwrap().read()),
    );
}

#[cold]
#[inline(never)]
fn clean_migrate_patched_dependencies_cold(
    old: &Lockfile,
    new: &mut Lockfile,
) -> Result<(), BunError> {
    let mut builder = string_builder!(new);
    for patched_dep in old.patched_dependencies.values() {
        builder.count(patched_dep.path.slice(old.buffers.string_bytes.as_slice()));
    }
    builder.allocate()?;
    for (k, v) in old
        .patched_dependencies
        .keys()
        .iter()
        .zip(old.patched_dependencies.values().iter())
    {
        debug_assert!(!v.patchfile_hash_is_null);
        let mut patchdep = *v;
        patchdep.path = builder
            .append::<SemverString>(patchdep.path.slice(old.buffers.string_bytes.as_slice()));
        new.patched_dependencies.put(*k, patchdep)?;
    }
    Ok(())
}

// ────────────────────────────────────────────────────────────────────────────
// MetaHashFormatter
// ────────────────────────────────────────────────────────────────────────────

pub struct MetaHashFormatter<'a> {
    pub meta_hash: &'a MetaHash,
}

impl<'a> fmt::Display for MetaHashFormatter<'a> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let remain: &[u8] = &self.meta_hash[..];

        // Alternating uppercase/lowercase hex groups; `HexBytes` emits two
        // digits per byte, contiguous, no separators.
        write!(
            f,
            "{}-{}-{}-{}",
            bun_core::fmt::HexBytes::<false>(&remain[0..8]),
            bun_core::fmt::HexBytes::<true>(&remain[8..16]),
            bun_core::fmt::HexBytes::<false>(&remain[16..24]),
            bun_core::fmt::HexBytes::<true>(&remain[24..32]),
        )
    }
}

impl Lockfile {
    pub fn fmt_meta_hash(&self) -> MetaHashFormatter<'_> {
        MetaHashFormatter {
            meta_hash: &self.meta_hash,
        }
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Cloner
// ────────────────────────────────────────────────────────────────────────────

pub struct Cloner<'a> {
    pub clone_queue: PendingResolutions,
    pub lockfile: &'a mut Lockfile,
    pub old: &'a mut Lockfile,
    pub mapping: &'a mut [PackageID],
    pub trees: tree::List,
    pub trees_count: u32,
    pub log: &'a mut bun_ast::Log,
    pub old_preinstall_state: Vec<Install::PreinstallState>,
    pub manager: &'a mut PackageManager,
}

impl<'a> Cloner<'a> {
    pub fn flush(&mut self) -> Result<(), BunError> {
        let max_package_id = self.old.packages.len();
        while let Some(to_clone) = self.clone_queue.pop() {
            let mapping = self.mapping[to_clone.old_resolution as usize];
            if (mapping as usize) < max_package_id {
                self.lockfile.buffers.resolutions[to_clone.resolve_id as usize] = mapping;
                continue;
            }

            let old_package = *self.old.packages.get(to_clone.old_resolution as usize);

            // `Package::clone` reads/writes through `cloner` exclusively.
            let new_id = old_package.clone(self)?;
            self.lockfile.buffers.resolutions[to_clone.resolve_id as usize] = new_id;
        }

        // cloning finished, items in lockfile buffer might have a different order, meaning
        // package ids and dependency ids have changed
        self.manager
            .clear_cached_items_depending_on_lockfile_buffer();

        if self.lockfile.packages.len() != 0 {
            self.lockfile.resolve(self.log)?;
        }

        // capacity is used for calculating byte size
        // so we need to make sure it's exact
        if self.lockfile.packages.capacity() != self.lockfile.packages.len()
            && self.lockfile.packages.len() > 0
        {
            self.lockfile
                .packages
                .shrink_and_free(self.lockfile.packages.len());
        }
        Ok(())
    }
}

// ────────────────────────────────────────────────────────────────────────────
// resolve / filter / hoist
// ────────────────────────────────────────────────────────────────────────────

impl Lockfile {
    pub fn resolve(&mut self, log: &mut bun_ast::Log) -> Result<(), tree::SubtreeError> {
        self.hoist::<{ tree::BuilderMethod::Resolvable }>(log, None, true, &[], None)
    }

    pub fn filter(
        &mut self,
        log: &mut bun_ast::Log,
        manager: &mut PackageManager,
        install_root_dependencies: bool,
        workspace_filters: &[WorkspaceFilter],
        packages_to_install: Option<&[PackageID]>,
    ) -> Result<(), tree::SubtreeError> {
        self.hoist::<{ tree::BuilderMethod::Filter }>(
            log,
            Some(manager),
            install_root_dependencies,
            workspace_filters,
            packages_to_install,
        )
    }

    /// Sets `buffers.trees` and `buffers.hoisted_dependencies`
    pub fn hoist<const METHOD: tree::BuilderMethod>(
        &mut self,
        log: &mut bun_ast::Log,
        // `tree::Builder` stores these unconditionally (Option/slice), so
        // accept the concrete shapes for all `METHOD`s.
        manager: Option<&PackageManager>,
        install_root_dependencies: bool,
        workspace_filters: &[WorkspaceFilter],
        packages_to_install: Option<&[PackageID]>,
    ) -> Result<(), tree::SubtreeError> {
        let slice = self.packages.slice();

        // `tree::Builder` stores `lockfile: ParentRef<Lockfile>` so
        // the `&mut buffers.resolutions` split-borrow below can coexist with
        // the read-only lockfile view inside the builder (see Tree.rs note).
        // `ParentRef::new` captures `SharedReadOnly` provenance from `&*self`,
        // which is exactly what `Builder` needs (it only ever `Deref`s); the
        // `Builder` does not outlive this `&mut self` borrow.
        let lockfile_ref = bun_ptr::ParentRef::<Lockfile>::new(&*self);
        let mut builder = tree::Builder::<METHOD> {
            queue: tree::TreeFiller::init(),
            resolution_lists: slice.items_resolutions(),
            resolutions: self.buffers.resolutions.as_mut_slice(),
            dependencies: self.buffers.dependencies.as_slice(),
            log,
            lockfile: lockfile_ref,
            manager,
            install_root_dependencies,
            workspace_filters,
            packages_to_install,
            pending_optional_peers: Default::default(),
            list: Default::default(),
            sort_buf: Default::default(),
        };

        Tree::default().process_subtree(tree::ROOT_DEP_ID, tree::INVALID_ID, &mut builder)?;

        // This goes breadth-first
        while let Some(item) = builder.queue.read_item() {
            use tree::BuilderEntryColumns as _;
            // Copy the element out of `builder.list` rather than indexing
            // in-place: `process_subtree` only reads `this.id`
            // (before appending to `builder.list`, which may reallocate), so the
            // copy is equivalent — and avoids the dangling-element hazard.
            let tree = builder.list.items_tree()[item.tree_id as usize];
            tree.process_subtree(item.dependency_id, item.hoist_root_id, &mut builder)?;
        }

        let cleaned = builder.clean()?;
        self.buffers.trees = cleaned.trees;
        self.buffers.hoisted_dependencies = cleaned.dep_ids;
        Ok(())
    }
}

#[derive(Clone, Copy)]
pub struct PendingResolution {
    pub old_resolution: PackageID,
    pub resolve_id: PackageID,
    pub parent: PackageID,
}

pub(crate) type PendingResolutions = Vec<PendingResolution>;

// ────────────────────────────────────────────────────────────────────────────
// fetchNecessaryPackageMetadataAfterYarnOrPnpmMigration
// ────────────────────────────────────────────────────────────────────────────

impl Lockfile {
    pub fn fetch_necessary_package_metadata_after_yarn_or_pnpm_migration<
        const UPDATE_OS_CPU: bool,
    >(
        &mut self,
        manager: &mut PackageManager,
    ) -> Result<(), AllocError> {
        if populate_manifest_cache::populate_manifest_cache(
            manager,
            populate_manifest_cache::Packages::All,
        )
        .is_err()
        {
            return Ok(());
        }

        let cache_ctx = manager.manifest_disk_cache_ctx();
        // `manifests` is a field of `manager`, and a `string_builder` is
        // opened on `manager.lockfile` while `&manifest` is still held.
        // Route the `manifests` projection
        // through a raw root so it can coexist with the lockfile borrows;
        // lockfile fields are taken from `self` (== `manager.lockfile`), never
        // re-derived via `manager_ptr`. BACKREF `mgr_ref` wraps the same root
        // for the read-only `options` projection so it goes through safe
        // `ParentRef::Deref`.
        let manager_ptr: *mut PackageManager = manager;
        let mgr_ref = bun_ptr::ParentRef::<PackageManager>::from(
            core::ptr::NonNull::new(manager_ptr).expect("derived from &mut, non-null"),
        );
        let mut pkgs = self.packages.slice();
        let len = pkgs.len();

        // `split_mut()` yields disjoint `&mut [_]` per column from one
        // `&mut Slice` borrow.
        let self::package::PackageColumnsMut {
            name: pkg_names,
            name_hash: pkg_name_hashes,
            resolution: pkg_resolutions,
            bin: pkg_bins,
            meta,
            ..
        } = pkgs.split_mut();
        // One loop serves both modes: bind `pkg_metas` as an empty slice
        // when the const generic is false.
        let pkg_metas: &mut [self::package::meta::Meta] =
            if UPDATE_OS_CPU { meta } else { &mut [] };

        for i in 0..len {
            let pkg_name = pkg_names[i];
            let pkg_name_hash = pkg_name_hashes[i];
            let pkg_res = pkg_resolutions[i];
            let pkg_bin = &mut pkg_bins[i];

            match pkg_res.tag {
                ResolutionTag::Npm => {
                    // `options` read via BACKREF `mgr_ref` (see hoisted note
                    // above); `manifests` and `lockfile` are non-overlapping
                    // fields and nothing below resizes/relocates `manifests`
                    // while `manifest` is held.
                    let scope = mgr_ref.options.scope_for_package_name(
                        pkg_name.slice(self.buffers.string_bytes.as_slice()),
                    );
                    // SAFETY: `manifests` projected from `manager_ptr`; the
                    // call holds only that disjoint field.
                    let Some(manifest) = unsafe { &mut (*manager_ptr).manifests }.by_name_hash(
                        cache_ctx,
                        scope,
                        pkg_name_hash,
                        Install::ManifestLoad::LoadFromMemoryFallbackToDisk,
                        false,
                    ) else {
                        continue;
                    };

                    let npm_ver = pkg_res.npm().version;
                    let Some(pkg) = manifest.find_by_version(npm_ver) else {
                        continue;
                    };

                    // `manager.lockfile` is the same `Lockfile` as `self`. Re-deriving a
                    // whole `&mut Lockfile` from `manager_ptr` here would create a
                    // second mutable reference aliasing `self` (UB) — go through
                    // `self` so the field-level borrows below stay disjoint from the
                    // live `pkg_*` column views (those point into the columnar heap
                    // allocation, not the `Lockfile` struct).
                    let mut builder = string_builder!(self);

                    let mut bin_extern_strings_count: u32 = 0;

                    bin_extern_strings_count += pkg.package.bin.count(
                        &manifest.string_buf,
                        &manifest.extern_strings_bin_entries,
                        &mut builder,
                    );

                    builder.allocate()?;
                    // `builder.clamp()` is called explicitly at end of block (no `?`
                    // exits between here and the clamp below).

                    let extern_strings_list = &mut self.buffers.extern_strings;
                    let start = extern_strings_list.len();
                    // Default-fill the tail so it is valid before `bin.clone`
                    // overwrites it (replaces `reserve` + raw `set_len`).
                    bun_core::vec::grow_default(
                        extern_strings_list,
                        bin_extern_strings_count as usize,
                    );
                    let new_len = extern_strings_list.len();

                    // A full slice and a tail subslice would alias, so
                    // `Bin::clone_with_buffers` takes the tail's offset for
                    // `ExternalStringList::init` directly.
                    let extern_strings_slice = &mut extern_strings_list[start..new_len];

                    *pkg_bin = pkg.package.bin.clone_with_buffers(
                        &manifest.string_buf,
                        &manifest.extern_strings_bin_entries,
                        start as u32,
                        extern_strings_slice,
                        &mut builder,
                    );

                    builder.clamp();

                    if UPDATE_OS_CPU {
                        let pkg_meta = &mut pkg_metas[i];
                        // Update os/cpu metadata if not already set
                        if pkg_meta.os == Npm::OperatingSystem::ALL {
                            pkg_meta.os = pkg.package.os;
                        }
                        if pkg_meta.arch == Npm::Architecture::ALL {
                            pkg_meta.arch = pkg.package.cpu;
                        }
                    }
                }
                _ => {}
            }
        }
        Ok(())
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Printer
// ────────────────────────────────────────────────────────────────────────────

pub struct Printer<'a> {
    pub lockfile: &'a Lockfile,
    pub options: &'a PackageManagerOptions,
    pub successfully_installed: Option<&'a DynamicBitSet>,
    pub updates: &'a [UpdateRequest],
}

#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PrinterFormat {
    Yarn,
}

pub mod printer {
    pub use super::printer_mods::tree_printer as Tree;
    pub use super::printer_mods::yarn as Yarn;
}

impl<'a> Printer<'a> {
    #[cold]
    pub fn print(
        log: &mut bun_ast::Log,
        input_lockfile_path: &[u8],
        format: PrinterFormat,
    ) -> Result<(), BunError> {
        // We truncate longer than allowed paths. We should probably throw an error instead.
        let path = &input_lockfile_path[..input_lockfile_path.len().min(MAX_PATH_BYTES)];

        let mut lockfile_path_buf1 = PathBuffer::uninit();
        let mut lockfile_path_buf2 = PathBuffer::uninit();

        let mut lockfile_path: &ZStr = ZStr::EMPTY;
        // Track which buffer backs `lockfile_path` so the chdir NUL-terminate
        // step below can write into the *other* buffer. `resolve_path::z` does
        // `output[..n].copy_from_slice(input)` (→ `ptr::copy_nonoverlapping`);
        // passing a slice of `bufN` as `input` while taking `&mut bufN` as
        // `output` is UB on overlapping ranges and would also corrupt
        // `lockfile_path` (printed in the NotFound arm).
        let mut path_in_buf2 = false;

        if !bun_paths::is_absolute(path) {
            // `bun_sys::getcwd` returns the length written into the
            // caller-owned buffer.
            let cwd_len = bun_sys::getcwd(&mut lockfile_path_buf1[..])?;
            let parts = [path];
            // Copy `cwd` out of `buf1` so the
            // join can write into `buf2` while `cwd` borrows `buf1` only.
            let cwd = &lockfile_path_buf1[..cwd_len];
            let lockfile_path__len = resolve_path::join_abs_string_buf::<platform::Auto>(
                cwd,
                &mut lockfile_path_buf2.0,
                &parts,
            )
            .len();
            lockfile_path_buf2[lockfile_path__len] = 0;
            // SAFETY: NUL written at [len] above. Not `from_buf`: borrowck
            // can't see that the `path_in_buf2` flag picks the *other* buffer
            // for the chdir scratch write below, so the borrow must be detached.
            lockfile_path =
                unsafe { ZStr::from_raw(lockfile_path_buf2.as_ptr(), lockfile_path__len) };
            path_in_buf2 = true;
        } else if !path.is_empty() {
            lockfile_path_buf1[..path.len()].copy_from_slice(path);
            lockfile_path_buf1[path.len()] = 0;
            // SAFETY: NUL written at [len] above. See note above re. borrowck.
            lockfile_path = unsafe { ZStr::from_raw(lockfile_path_buf1.as_ptr(), path.len()) };
        }

        if !lockfile_path.as_bytes().is_empty() && lockfile_path.as_bytes()[0] == SEP {
            let dir = bun_paths::dirname(lockfile_path.as_bytes()).unwrap_or(SEP_STR.as_bytes());
            // NUL-terminate into the buffer that does NOT back `lockfile_path`
            // (see `path_in_buf2` note above). `buf1`'s cwd contents are dead
            // after the join, so it is free for reuse here.
            let dir_z = if path_in_buf2 {
                resolve_path::z(dir, &mut lockfile_path_buf1)
            } else {
                resolve_path::z(dir, &mut lockfile_path_buf2)
            };
            let _ = sys::chdir(dir_z);
        }

        // Bootstrap the resolver FS singleton. `Printer::print` is an entry
        // point (`bun bun.lockb`), so
        // the singleton may not exist yet.
        let _ = FileSystem::init(None)?;

        let mut lockfile = Box::<Lockfile>::default();

        let load_from_disk = lockfile.load_from_cwd::<false>(None, log);
        match load_from_disk {
            crate::lockfile::LoadResult::Err(cause) => {
                match cause.step {
                    crate::lockfile::LoadStep::OpenFile => bun_core::pretty_errorln!(
                        "<r><red>error<r> opening lockfile:<r> {}.",
                        cause.value.name()
                    ),
                    crate::lockfile::LoadStep::ParseFile => bun_core::pretty_errorln!(
                        "<r><red>error<r> parsing lockfile:<r> {}",
                        cause.value.name()
                    ),
                    crate::lockfile::LoadStep::ReadFile => bun_core::pretty_errorln!(
                        "<r><red>error<r> reading lockfile:<r> {}",
                        cause.value.name()
                    ),
                    crate::lockfile::LoadStep::Migrating => bun_core::pretty_errorln!(
                        "<r><red>error<r> while migrating lockfile:<r> {}",
                        cause.value.name()
                    ),
                }
                if log.errors > 0 {
                    // `IntoLogWrite` is implemented for `*mut bun_core::io::Writer`,
                    // not `&mut &mut Writer` — pass the raw vtable pointer.
                    let ew: *mut bun_core::io::Writer = Output::error_writer();
                    log.print(ew)?;
                }
                Global::crash();
            }
            crate::lockfile::LoadResult::NotFound => {
                bun_core::pretty_errorln!(
                    "<r><red>lockfile not found:<r> {}",
                    bun_core::fmt::QuotedFormatter {
                        text: lockfile_path.as_bytes()
                    },
                );
                Global::crash();
            }
            crate::lockfile::LoadResult::Ok(_) => {}
        }

        let writer = Output::writer_buffered();
        match Self::print_with_lockfile(&lockfile, format, writer) {
            Ok(()) => {}
            Err(e) if e == err!("OutOfMemory") => bun_core::out_of_memory(),
            Err(e) if e == err!("BrokenPipe") || e == err!("WriteFailed") => return Ok(()),
            Err(e) => return Err(e),
        }
        Output::flush();
        Ok(())
    }

    pub fn print_with_lockfile<W: bun_io::Write>(
        lockfile: &Lockfile,
        format: PrinterFormat,
        writer: W,
    ) -> Result<(), BunError> {
        // `FileSystem::init` ran in the caller (`Printer::print`); this is the
        // process-static singleton. Single-threaded
        // CLI path, no concurrent access.
        let fs = FileSystem::instance();
        let mut options = PackageManagerOptions {
            max_concurrent_lifecycle_scripts: 1,
            ..Default::default()
        };

        // Capture the `'static` cwd slice
        // before borrowing `fs.fs` mutably.
        let top_level_dir = fs.top_level_dir;
        let entries_option = fs.fs.read_directory(top_level_dir, None, 0, true)?;
        let entries: &mut Fs::DirEntry = match entries_option {
            Fs::EntriesOption::Entries(e) => &mut **e,
            Fs::EntriesOption::Err(e) => return Err(e.canonical_error),
        };

        // PORTING.md §Forbidden patterns: never `Box::leak` — own `map`/`loader` as locals;
        // they live for the function scope (one-shot CLI path).
        let mut map = DotEnv::Map::init();
        let mut env_loader = DotEnv::Loader::init(&mut map);
        env_loader.quiet = true;

        env_loader.load_process()?;
        // `DotEnv::Loader::load` takes `impl DirEntryProbe` (bun_dotenv sits
        // below `bun_resolver` in the crate graph); `Fs::DirEntry` impls it.
        env_loader.load(
            &*entries,
            &[] as &[&[u8]],
            DotEnv::DotEnvFileSuffix::Production,
            false,
        )?;
        let mut log = bun_ast::Log::init();
        options.load(
            &mut log,
            &mut env_loader,
            None,
            None,
            crate::Subcommand::Install,
        )?;

        let mut printer = Printer {
            lockfile,
            options: &options,
            successfully_installed: None,
            updates: &[],
        };

        let mut writer = writer;
        match format {
            PrinterFormat::Yarn => {
                printer::Yarn::print(&mut printer, &mut writer)?;
            }
        }
        Ok(())
    }
}

// ────────────────────────────────────────────────────────────────────────────
// verifyData / saveToDisk / rootPackage / str / initEmpty
// ────────────────────────────────────────────────────────────────────────────

impl Lockfile {
    pub fn verify_data(&self) -> Result<(), BunError> {
        debug_assert!(self.format == FormatVersion::current());
        let mut i: usize = 0;
        while i < self.packages.len() {
            let package: Package = *self.packages.get(i);
            debug_assert!(self.str(&package.name).len() == package.name.len());
            debug_assert!(
                SemverStringBuilder::string_hash(self.str(&package.name)) == package.name_hash
            );
            debug_assert!(
                package
                    .dependencies
                    .get(self.buffers.dependencies.as_slice())
                    .len()
                    == package.dependencies.len as usize
            );
            debug_assert!(
                package
                    .resolutions
                    .get(self.buffers.resolutions.as_slice())
                    .len()
                    == package.resolutions.len as usize
            );
            debug_assert!(
                package
                    .resolutions
                    .get(self.buffers.resolutions.as_slice())
                    .len()
                    == package.dependencies.len as usize
            );
            let dependencies = package
                .dependencies
                .get(self.buffers.dependencies.as_slice());
            for dependency in dependencies {
                debug_assert!(self.str(&dependency.name).len() == dependency.name.len());
                debug_assert!(
                    SemverStringBuilder::string_hash(self.str(&dependency.name))
                        == dependency.name_hash
                );
            }
            i += 1;
        }
        Ok(())
    }

    pub fn save_to_disk(&mut self, load_result: &LoadResult<'_>, options: &PackageManagerOptions) {
        let save_format = load_result.save_format(options);
        if cfg!(debug_assertions) {
            if let Err(e) = self.verify_data() {
                bun_core::pretty_errorln!(
                    "<r><red>error:<r> failed to verify lockfile: {}",
                    e.name()
                );
                Global::crash();
            }
            debug_assert!(Fs::INSTANCE_LOADED.load(core::sync::atomic::Ordering::Relaxed));
        }

        let bytes: Vec<u8> = 'bytes: {
            if save_format == LockfileFormat::Text {
                let mut writer_buf: Vec<u8> = Vec::new();

                if let Err(_e) = TextLockfile::Stringifier::save_from_binary(
                    self,
                    load_result,
                    options,
                    &mut writer_buf,
                ) {
                    // The only write failure on an allocating writer is OOM.
                    bun_core::out_of_memory();
                }

                // writer.flush() catch error.WriteFailed -> OOM
                // (Vec<u8> writer needs no flush)

                break 'bytes writer_buf;
            }

            let mut bytes: Vec<u8> = Vec::new();

            let mut total_size: usize = 0;
            let mut end_pos: usize = 0;
            if let Err(e) =
                Serializer::save(self, options, &mut bytes, &mut total_size, &mut end_pos)
            {
                Output::err(e, "failed to serialize lockfile", format_args!(""));
                Global::crash();
            }
            if bytes.len() >= end_pos {
                bytes[end_pos..end_pos + core::mem::size_of::<usize>()]
                    .copy_from_slice(&total_size.to_ne_bytes());
            }
            break 'bytes bytes;
        };
        // defer bun.default_allocator.free(bytes) — Vec drops at scope end.

        let mut tmpname_buf = [0u8; 512];
        let mut base64_bytes = [0u8; 8];
        bun_core::csprng(&mut base64_bytes);
        let tmpname: &ZStr = {
            let mut cursor: &mut [u8] = &mut tmpname_buf[..];
            let start_len = cursor.len();
            if save_format == LockfileFormat::Text {
                write!(
                    cursor,
                    ".lock-{}.tmp\0",
                    bun_core::fmt::HexBytes::<true>(&base64_bytes)
                )
                .expect("unreachable");
            } else {
                write!(
                    cursor,
                    ".lockb-{}.tmp\0",
                    bun_core::fmt::HexBytes::<true>(&base64_bytes)
                )
                .expect("unreachable");
            }
            let written = start_len - cursor.len();
            ZStr::from_buf(&tmpname_buf, written - 1)
        };

        let file = match File::openat(Fd::cwd(), tmpname, sys::O::CREAT | sys::O::WRONLY, 0o777) {
            sys::Result::Err(e) => {
                Output::err(
                    e,
                    "failed to create temporary file to save lockfile",
                    format_args!(""),
                );
                Global::crash();
            }
            sys::Result::Ok(f) => f,
        };

        match file.write_all(&bytes) {
            sys::Result::Err(e) => {
                let _ = file.close(); // close error is non-actionable
                let _ = sys::unlink(tmpname);
                Output::err(e, "failed to write lockfile", format_args!(""));
                Global::crash();
            }
            sys::Result::Ok(()) => {}
        }

        #[cfg(unix)]
        {
            // chmod 755 for binary, 644 for plaintext
            let mut filemode: sys::Mode = 0o755;
            if save_format == LockfileFormat::Text {
                filemode = 0o644;
            }
            match sys::fchmod(file.handle, filemode) {
                sys::Result::Err(e) => {
                    let _ = file.close(); // close error is non-actionable
                    let _ = sys::unlink(tmpname);
                    Output::err(e, "failed to change lockfile permissions", format_args!(""));
                    Global::crash();
                }
                sys::Result::Ok(()) => {}
            }
        }

        if let Err(e) = file.close_and_move_to(tmpname, save_format.filename()) {
            bun_core::handle_error_return_trace(e);

            // note: file is already closed here.
            let _ = sys::unlink(tmpname);

            Output::err(
                e,
                "Failed to replace old lockfile with new lockfile on disk",
                format_args!(""),
            );
            Global::crash();
        }
    }

    pub fn root_package(&self) -> Option<Package> {
        if self.packages.len() == 0 {
            return None;
        }

        Some(*self.packages.get(0))
    }

    #[inline]
    pub fn str<'a, T: bun_semver::Slicable>(&'a self, slicable: &'a T) -> &'a [u8] {
        slicable.slice(self.buffers.string_bytes.as_slice())
    }

    /// [`str`](Self::str) with the borrow detached from `self`.
    ///
    /// The install pipeline frequently needs to read a string out of
    /// `buffers.string_bytes` and then call back into `&mut PackageManager`
    /// (which owns the `Lockfile`). The caller would otherwise have to write
    /// `unsafe { detach_lifetime(self.str(x)) }` at
    /// every site. Consolidating that here keeps the SAFETY argument in one
    /// place.
    ///
    /// SAFETY (internal): `string_bytes` is append-only for the lifetime of a
    /// resolve/enqueue pass and is never reallocated while a detached slice is
    /// live. The returned slice must not outlive the
    /// `Lockfile`.
    #[inline]
    pub fn str_detached<'a, T: bun_semver::Slicable>(&self, slicable: &T) -> &'a [u8] {
        // SAFETY: see doc comment — same invariant every prior call site
        // already relied on via `bun_ptr::detach_lifetime`.
        unsafe { bun_ptr::detach_lifetime(slicable.slice(self.buffers.string_bytes.as_slice())) }
    }

    /// Construct an empty Lockfile value in place.
    pub fn init_empty(&mut self) {
        *self = Self::init_empty_value();
    }
}

impl Default for Lockfile {
    #[inline]
    fn default() -> Self {
        Self::init_empty_value()
    }
}

impl Lockfile {
    pub fn init_empty_value() -> Self {
        Lockfile {
            format: FormatVersion::current(),
            text_lockfile_version: bun_lock::Version::current(),
            packages: Default::default(),
            buffers: Buffers::default(),
            package_index: PackageIndexMap::default(),
            string_pool: StringPool::default(),
            scratch: Scratch::init(),
            scripts: Scripts::default(),
            trusted_dependencies: None,
            workspace_paths: NameHashMap::default(),
            workspace_versions: VersionHashMap::default(),
            overrides: OverrideMap::default(),
            catalogs: CatalogMap::default(),
            meta_hash: ZERO_HASH,
            patched_dependencies: PatchedDependenciesMap::default(),
            saved_config_version: None,
            // Fresh lockfile (no load): every package appended later is
            // session-appended, so the order-independence guard in
            // `get_package_id` applies from id 0.
            loaded_package_count: 0,
            exact_pinned: DynamicBitSet::default(),
        }
    }

    /// Snapshot `packages.len()` as the "loaded from lockfile" watermark.
    /// Call exactly once after `load_from_cwd` (including npm/pnpm/yarn
    /// migration) before any manifest-driven `append_package`.
    #[inline]
    pub fn mark_loaded_packages(&mut self) {
        self.loaded_package_count = self.packages.len() as PackageID;
    }

    /// Record that package `id` was appended via an exact-version dependency
    /// (`=X.Y.Z`). See the `exact_pinned` field doc.
    #[inline]
    pub fn mark_exact_pin(&mut self, id: PackageID) {
        let i = id as usize;
        if self.exact_pinned.bit_length() <= i {
            bun_core::handle_oom(self.exact_pinned.resize(i + 1, false));
        }
        self.exact_pinned.set(i);
    }

    pub fn get_package_id(
        &self,
        name_hash: u64,
        // If non-null, attempt to use an existing package
        // that satisfies this version range.
        version: Option<&DependencyVersion>,
        resolution: &Resolution,
    ) -> Option<PackageID> {
        let entry = self.package_index.get(&name_hash)?;
        let resolutions: &[Resolution] = self.packages.items_resolution();
        // Borrow the `npm` arm's `Semver::Group` (not `Copy` — owns a linked
        // list head). `version` is held by-value for the whole fn body so the
        // borrow is sound.
        let npm_version = match version {
            Some(v) if v.tag == dependency::Tag::Npm => Some(&v.npm().version),
            _ => None,
        };
        // Order-independence guard for the `satisfies` fallback below: when the
        // caller already knows the manifest's best-match version (the npm
        // `resolution` it passes), only dedupe to an existing entry whose
        // version is at least that. Without this, the result depends on which
        // sibling's manifest happened to land first — `*` deduping to a
        // previously-appended `1.0.2` instead of resolving to `2.0.2` is the
        // long-standing "text lockfile is hoisted" flake. Lockfile-pinned deps
        // are kept out of this codepath by `Diff::generate`'s
        // satisfies-preserves-mapping rule (which keeps the resolution slot
        // populated so the early return in `get_or_put_resolved_package` fires
        // before we get here).
        let resolved_npm_floor = if resolution.tag == ResolutionTag::Npm {
            Some(resolution.npm().version)
        } else {
            None
        };
        let buf = self.buffers.string_bytes.as_slice();

        let loaded_watermark = self.loaded_package_count;
        let exact_pinned = &self.exact_pinned;
        let try_satisfies_dedupe = |id: PackageID| -> bool {
            let existing = &resolutions[id as usize];
            if existing.tag != ResolutionTag::Npm {
                return false;
            }
            let Some(npm_v) = npm_version else {
                return false;
            };
            let existing_ver = existing.npm().version;
            if !npm_v.satisfies(existing_ver, buf, buf) {
                return false;
            }
            // Order-independence guard. We refuse to dedupe a wide range to a
            // *lower* existing entry only when ALL of the following hold:
            //   - the entry was appended in this resolve session
            //     (lockfile-loaded entries are the user's existing pin),
            //   - the entry was NOT appended for an exact-`=X.Y.Z` dependency
            //     (an exact pin anywhere in the tree is a deliberate choice,
            //     not a network-order artefact — `dragon test 2` /
            //     "dependency from root satisfies range from dependency"),
            //   - the manifest's best-match is a *different major* (within a
            //     major, deduping to an older patch is the long-standing
            //     behaviour and the worst case is still ^-compatible).
            // What this leaves is exactly the cross-parent network-order
            // flake: a wide range (`*`, `>=X`) collapsing onto a sibling's
            // *range-resolved* lower major depending on whose manifest landed
            // first ("text lockfile is hoisted").
            if id >= loaded_watermark && !exact_pinned.is_set_allow_out_of_bound(id as usize, false)
            {
                if let Some(floor) = resolved_npm_floor {
                    if existing_ver.order(floor, buf, buf) == Ordering::Less
                        && existing_ver.major != floor.major
                    {
                        return false;
                    }
                }
            }
            true
        };

        match entry {
            PackageIndexEntry::Id(id) => {
                if cfg!(debug_assertions) {
                    debug_assert!((*id as usize) < resolutions.len());
                }

                if resolutions[*id as usize].eql(resolution, buf, buf) {
                    return Some(*id);
                }

                if try_satisfies_dedupe(*id) {
                    return Some(*id);
                }
            }
            PackageIndexEntry::Ids(ids) => {
                for &id in ids.iter() {
                    if cfg!(debug_assertions) {
                        debug_assert!((id as usize) < resolutions.len());
                    }

                    if resolutions[id as usize].eql(resolution, buf, buf) {
                        return Some(id);
                    }

                    if try_satisfies_dedupe(id) {
                        return Some(id);
                    }
                }
            }
        }

        None
    }

    /// Appends `pkg` to `this.packages`, and adds to `this.package_index`.
    ///
    /// The string buffer is read from `self`, splitting borrows at the field
    /// level (`package_index` / `packages` / `buffers.string_bytes` are
    /// disjoint).
    pub fn append_package_dedupe(&mut self, pkg: &mut Package) -> Result<PackageID, AllocError> {
        let entry = self.package_index.get_or_put(pkg.name_hash)?;

        if !entry.found_existing {
            let new_id: PackageID = PackageID::try_from(self.packages.len()).expect("int cast");
            pkg.meta.id = new_id;
            self.packages.append(*pkg)?;
            *entry.value_ptr = PackageIndexEntry::Id(new_id);
            return Ok(new_id);
        }

        let buf = self.buffers.string_bytes.as_slice();
        let mut resolutions = self.packages.items_resolution();

        match entry.value_ptr {
            PackageIndexEntry::Id(existing_id) => {
                let existing_id = *existing_id;
                if pkg
                    .resolution
                    .eql(&resolutions[existing_id as usize], buf, buf)
                {
                    pkg.meta.id = existing_id;
                    return Ok(existing_id);
                }

                let new_id: PackageID = PackageID::try_from(self.packages.len()).expect("int cast");
                pkg.meta.id = new_id;
                self.packages.append(*pkg)?;

                resolutions = self.packages.items_resolution();

                let pair = if pkg
                    .resolution
                    .order(&resolutions[existing_id as usize], buf, buf)
                    == Ordering::Greater
                {
                    [new_id, existing_id]
                } else {
                    [existing_id, new_id]
                };
                let mut ids = PackageIDList::with_capacity(8);
                ids.extend_from_slice(&pair);

                *entry.value_ptr = PackageIndexEntry::Ids(ids);

                Ok(new_id)
            }
            PackageIndexEntry::Ids(existing_ids) => {
                for &existing_id in existing_ids.iter() {
                    if pkg
                        .resolution
                        .eql(&resolutions[existing_id as usize], buf, buf)
                    {
                        pkg.meta.id = existing_id;
                        return Ok(existing_id);
                    }
                }

                let new_id: PackageID = PackageID::try_from(self.packages.len()).expect("int cast");
                pkg.meta.id = new_id;
                self.packages.append(*pkg)?;

                resolutions = self.packages.items_resolution();

                for i in 0..existing_ids.len() {
                    let existing_id = existing_ids[i];
                    if pkg
                        .resolution
                        .order(&resolutions[existing_id as usize], buf, buf)
                        == Ordering::Greater
                    {
                        existing_ids.insert(i, new_id);
                        return Ok(new_id);
                    }
                }

                existing_ids.push(new_id);

                Ok(new_id)
            }
        }
    }

    pub fn get_or_put_id(
        &mut self,
        id: PackageID,
        name_hash: PackageNameHash,
    ) -> Result<(), AllocError> {
        let gpe = self.package_index.get_or_put(name_hash)?;

        if gpe.found_existing {
            let index: &mut PackageIndexEntry = gpe.value_ptr;

            match index {
                PackageIndexEntry::Id(existing_id) => {
                    let existing_id = *existing_id;
                    let resolutions = self.packages.items_resolution();
                    let buf = self.buffers.string_bytes.as_slice();

                    let pair = if resolutions[id as usize].order(
                        &resolutions[existing_id as usize],
                        buf,
                        buf,
                    ) == Ordering::Greater
                    {
                        [id, existing_id]
                    } else {
                        [existing_id, id]
                    };
                    let mut ids = PackageIDList::with_capacity(8);
                    ids.extend_from_slice(&pair);

                    *index = PackageIndexEntry::Ids(ids);
                }
                PackageIndexEntry::Ids(existing_ids) => {
                    let resolutions = self.packages.items_resolution();
                    let buf = self.buffers.string_bytes.as_slice();

                    for i in 0..existing_ids.len() {
                        let existing_id = existing_ids[i];
                        if resolutions[id as usize].order(
                            &resolutions[existing_id as usize],
                            buf,
                            buf,
                        ) == Ordering::Greater
                        {
                            existing_ids.insert(i, id);
                            return Ok(());
                        }
                    }

                    // append to end because it's the smallest or equal to the smallest
                    existing_ids.push(id);
                }
            }
        } else {
            *gpe.value_ptr = PackageIndexEntry::Id(id);
        }
        Ok(())
    }

    pub fn append_package(&mut self, package_: &Package) -> Result<Package, AllocError> {
        let id: PackageID = self.packages.len() as PackageID;
        self.append_package_with_id(package_, id)
    }

    pub fn append_package_with_id(
        &mut self,
        package_: &Package,
        id: PackageID,
    ) -> Result<Package, AllocError> {
        // Captured for the assertion at the end of the function.
        let name_hash = package_.name_hash;
        let resolution = package_.resolution;

        let mut package = *package_;
        package.meta.id = id;
        self.packages.append(package)?;
        self.get_or_put_id(id, name_hash)?;

        if cfg!(debug_assertions) {
            debug_assert!(self.get_package_id(name_hash, None, &resolution).is_some());
        }

        Ok(package)
    }

    #[inline]
    pub fn string_builder(&mut self) -> StringBuilder<'_> {
        StringBuilder {
            len: 0,
            cap: 0,
            off: 0,
            ptr: None,
            string_bytes: &mut self.buffers.string_bytes,
            string_pool: &mut self.string_pool,
        }
    }

    /// Borrowck-approved disjoint split: returns a fresh `StringBuilder`
    /// (borrowing `buffers.string_bytes` + `string_pool`) alongside mutable
    /// references to every other `Lockfile` field a caller might need while
    /// the builder is live. Use this instead of routing through
    /// `*mut Lockfile` + `unsafe { &mut (*ptr).field }` reborrows.
    #[inline]
    pub fn string_builder_split(&mut self) -> (StringBuilder<'_>, LockfileFields<'_>) {
        let Buffers {
            string_bytes,
            dependencies,
            resolutions,
            extern_strings,
            trees,
            hoisted_dependencies,
        } = &mut self.buffers;
        (
            StringBuilder {
                len: 0,
                cap: 0,
                off: 0,
                ptr: None,
                string_bytes,
                string_pool: &mut self.string_pool,
            },
            LockfileFields {
                packages: &mut self.packages,
                dependencies,
                resolutions,
                extern_strings,
                trees,
                hoisted_dependencies,
                package_index: &mut self.package_index,
                overrides: &mut self.overrides,
                catalogs: &mut self.catalogs,
                workspace_paths: &mut self.workspace_paths,
                workspace_versions: &mut self.workspace_versions,
                patched_dependencies: &mut self.patched_dependencies,
                trusted_dependencies: &mut self.trusted_dependencies,
                scripts: &mut self.scripts,
            },
        )
    }

    pub fn string_buf(&mut self) -> SemverStringBuf<'_> {
        SemverStringBuf {
            bytes: &mut self.buffers.string_bytes,
            pool: &mut self.string_pool,
        }
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Scratch
// ────────────────────────────────────────────────────────────────────────────

pub struct Scratch {
    pub duplicate_checker_map: DuplicateCheckerMap,
    pub dependency_list_queue: DependencyQueue,
}

pub(crate) type DuplicateCheckerMap =
    BunHashMap<PackageNameHash, bun_ast::Loc, IdentityContext<PackageNameHash>>;
pub(crate) type DependencyQueue = LinearFifo<DependencySlice, DynamicBuffer<DependencySlice>>;

impl Scratch {
    pub(crate) fn init() -> Scratch {
        Scratch {
            dependency_list_queue: DependencyQueue::init(),
            duplicate_checker_map: DuplicateCheckerMap::default(),
        }
    }
}

impl Default for Scratch {
    fn default() -> Self {
        Self::init()
    }
}

// ────────────────────────────────────────────────────────────────────────────
// LockfileFields — disjoint split borrow alongside StringBuilder
// ────────────────────────────────────────────────────────────────────────────

/// Mutable references to every `Lockfile` field that is *disjoint* from the
/// two columns a `StringBuilder` borrows (`buffers.string_bytes` +
/// `string_pool`). Returned by `Lockfile::string_builder_split()` so callers
/// can hold a live builder and still touch `packages` / `buffers.dependencies`
/// / `overrides` / … without raw-pointer reborrow gymnastics.
pub struct LockfileFields<'a> {
    pub packages: &'a mut PackageList,
    pub dependencies: &'a mut DependencyList,
    pub resolutions: &'a mut PackageIDList,
    pub extern_strings: &'a mut ExternalStringBuffer,
    pub trees: &'a mut tree::List,
    pub hoisted_dependencies: &'a mut DependencyIDList,
    pub package_index: &'a mut PackageIndexMap,
    pub overrides: &'a mut OverrideMap,
    pub catalogs: &'a mut CatalogMap,
    pub workspace_paths: &'a mut NameHashMap,
    pub workspace_versions: &'a mut VersionHashMap,
    pub patched_dependencies: &'a mut PatchedDependenciesMap,
    pub trusted_dependencies: &'a mut Option<TrustedDependenciesSet>,
    pub scripts: &'a mut Scripts,
}

// ────────────────────────────────────────────────────────────────────────────
// StringBuilder
// ────────────────────────────────────────────────────────────────────────────

/// Holds the two fields the builder actually mutates (rather than a whole
/// `&mut Lockfile`, which would block every caller from touching disjoint
/// fields like `packages` / `buffers.dependencies` while a builder is alive)
/// so callers can split-borrow at the field level.
pub struct StringBuilder<'a> {
    pub len: usize,
    pub cap: usize,
    pub off: usize,
    pub ptr: Option<*mut u8>,
    pub string_bytes: &'a mut Vec<u8>,
    pub string_pool: &'a mut StringPool,
}

/// Construct a `StringBuilder` with a *field-level* split borrow of `$lockfile`
/// (`buffers.string_bytes` + `string_pool`). Use this — not the
/// `Lockfile::string_builder()` method — at sites that also need to read other
/// `$lockfile` fields while the builder is live; the method form borrows the
/// whole struct.
#[macro_export]
macro_rules! string_builder {
    ($lockfile:expr) => {
        $crate::lockfile_real::StringBuilder {
            len: 0,
            cap: 0,
            off: 0,
            ptr: None,
            string_bytes: &mut $lockfile.buffers.string_bytes,
            string_pool: &mut $lockfile.string_pool,
        }
    };
}

/// Trait implemented by `String` and `ExternalString` to support generic `append*`.
/// Canonical def lives in
/// `bun_semver::semver_string`; re-exported under the local name so generic
/// bounds in this module (`append<T: StringBuilderType>`) are unchanged.
pub use bun_semver::semver_string::BuilderStringType as StringBuilderType;

impl<'a> StringBuilder<'a> {
    #[inline]
    pub fn count(&mut self, slice: &[u8]) {
        self.assert_not_allocated();

        if SemverString::can_inline(slice) {
            return;
        }
        self._count_with_hash(slice, SemverStringBuilder::string_hash(slice));
    }

    #[inline]
    pub fn count_with_hash(&mut self, slice: &[u8], hash: u64) {
        self.assert_not_allocated();

        if SemverString::can_inline(slice) {
            return;
        }
        self._count_with_hash(slice, hash);
    }

    #[inline]
    fn assert_not_allocated(&self) {
        if cfg!(debug_assertions) {
            if self.ptr.is_some() {
                Output::panic(format_args!(
                    "StringBuilder.count called after StringBuilder.allocate. This is a bug in Bun. Please make sure to call StringBuilder.count before allocating."
                ));
            }
        }
    }

    #[inline]
    fn _count_with_hash(&mut self, slice: &[u8], hash: u64) {
        self.assert_not_allocated();

        if !self.string_pool.contains(hash) {
            self.cap += slice.len();
        }
    }

    pub fn allocated_slice(&self) -> &[u8] {
        // `allocate()` resized `string_bytes` to `off + cap` and recorded `off`,
        // so the region is addressable by safe indexing — no need for the cached
        // raw `ptr`.
        if self.ptr.is_some() {
            &self.string_bytes[self.off..self.off + self.cap]
        } else {
            b""
        }
    }

    pub fn clamp(&mut self) {
        if cfg!(debug_assertions) {
            debug_assert!(self.cap >= self.len);
            // assert that no other builder was allocated while this builder was being used
            debug_assert!(self.string_bytes.len() == self.off + self.cap);
        }

        let excess = self.cap - self.len;

        if excess > 0 {
            let new_len = self.string_bytes.len() - excess;
            self.string_bytes.truncate(new_len);
        }
    }

    pub fn allocate(&mut self) -> Result<(), AllocError> {
        let string_bytes = &mut *self.string_bytes;
        let prev_len = string_bytes.len();
        // Zero-extend rather than `set_len` over uninit: `as_slice()` callers
        // (lockfile.rs:2624/2644/2649/2668, dependency.rs:327, CatalogMap.rs:173)
        // read the full slice including the not-yet-appended tail. Matches the
        // `grow_default` precedent at :1578.
        string_bytes.resize(prev_len + self.cap, 0);
        self.off = prev_len;
        // SAFETY: `string_bytes` was just resized to `prev_len + self.cap`, so
        // offsetting its base pointer by `prev_len` stays within the allocation.
        self.ptr = Some(unsafe { string_bytes.as_mut_ptr().add(prev_len) });
        self.len = 0;
        Ok(())
    }

    #[inline]
    pub fn append<T: StringBuilderType>(&mut self, slice: &[u8]) -> T {
        self.append_with_hash::<T>(slice, SemverStringBuilder::string_hash(slice))
    }

    /// SlicedString is not supported due to inline strings.
    pub fn append_without_pool<T: StringBuilderType>(&mut self, slice: &[u8], hash: u64) -> T {
        if SemverString::can_inline(slice) {
            return T::from_init(self.string_bytes.as_slice(), slice, hash);
        }
        if cfg!(debug_assertions) {
            debug_assert!(self.len <= self.cap); // didn't count everything
            debug_assert!(self.ptr.is_some()); // must call allocate first
        }

        // `allocate()` resized `string_bytes` to `off + cap`; write via safe
        // indexing instead of the cached raw `ptr` + `copy_nonoverlapping`.
        let start = self.off + self.len;
        let end = start + slice.len();
        self.string_bytes[start..end].copy_from_slice(slice);
        let final_slice = &self.string_bytes[start..end];
        self.len += slice.len();

        if cfg!(debug_assertions) {
            debug_assert!(self.len <= self.cap);
        }

        T::from_init(self.string_bytes.as_slice(), final_slice, hash)
    }

    pub fn append_with_hash<T: StringBuilderType>(&mut self, slice: &[u8], hash: u64) -> T {
        if SemverString::can_inline(slice) {
            return T::from_init(self.string_bytes.as_slice(), slice, hash);
        }

        if cfg!(debug_assertions) {
            debug_assert!(self.len <= self.cap); // didn't count everything
            debug_assert!(self.ptr.is_some()); // must call allocate first
        }

        let string_entry = self.string_pool.get_or_put(hash).expect("unreachable");
        if !string_entry.found_existing {
            // See `append_without_pool` — safe indexing into the region
            // `allocate()` already resized.
            let start = self.off + self.len;
            let end = start + slice.len();
            self.string_bytes[start..end].copy_from_slice(slice);
            let final_slice = &self.string_bytes[start..end];
            self.len += slice.len();

            *string_entry.value_ptr = SemverString::init(self.string_bytes.as_slice(), final_slice);
        }

        if cfg!(debug_assertions) {
            debug_assert!(self.len <= self.cap);
        }

        T::from_pooled(*string_entry.value_ptr, hash)
    }
}

// ─── StringBuilder trait wiring ─────────────────────────────────────────────
//
// Several callees (`Version::count`/`append`, `Dependency::count`/`clone`,
// `Bin::count`/`clone`, `Scripts::clone`/`count`) accept the builder via a
// duck-typed trait. Wire
// `lockfile::StringBuilder` into each so `Package` can pass `&mut builder`
// straight through.

impl<'a> bun_semver::StringBuilder for StringBuilder<'a> {
    #[inline]
    fn count(&mut self, slice_: &[u8]) {
        StringBuilder::count(self, slice_)
    }
    #[inline]
    fn append<T: bun_semver::semver_string::BuilderStringType>(&mut self, slice_: &[u8]) -> T {
        StringBuilder::append::<T>(self, slice_)
    }
}

// `crate::dependency::StringBuilderLike` impl lives in `dependency.rs` next to
// the trait definition (it needs `string_bytes()` access to the lockfile
// buffers). `bin_real::StringBuilder` is now a re-export of
// `bun_semver::StringBuilder`, so the impl above covers it; `package::scripts`
// takes `&mut StringBuilder<'_>` concretely, so no adapter trait is needed
// there either.

// ────────────────────────────────────────────────────────────────────────────
// PackageIndex
// ────────────────────────────────────────────────────────────────────────────

pub mod package_index {
    use super::*;

    // `bun_collections::HashMap` hard-codes an 80% max load factor.
    pub type Map = BunHashMap<PackageNameHash, Entry, IdentityContext<PackageNameHash>>;

    #[repr(u8)]
    pub enum Tag {
        Id = 0,
        Ids = 1,
    }

    pub enum Entry {
        Id(PackageID),
        Ids(PackageIDList),
    }

    impl Default for Entry {
        /// `HashMap::get_or_put` needs a `Default` to fill the value slot before
        /// the caller writes the real `Entry::Id(..)` / `Entry::Ids(..)`.
        #[inline]
        fn default() -> Self {
            Entry::Id(0)
        }
    }
}

pub use package_index::Entry as PackageIndexEntry;
pub use package_index::Map as PackageIndexMap;

// ────────────────────────────────────────────────────────────────────────────
// FormatVersion
// ────────────────────────────────────────────────────────────────────────────

/// The binary lockfile serializer reads this u32 directly from disk; an
/// exhaustive Rust enum would
/// make deserializing a future v4+ lockfile instant UB (transmute-to-enum with an
/// invalid discriminant). PORTING.md §Forbidden patterns: never transmute disk data
/// into an exhaustive enum. Represent as a transparent u32 with associated consts so
/// unknown values round-trip and can be compared against `current()` for a graceful
/// version-mismatch error.
#[repr(transparent)]
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct FormatVersion(pub u32);

impl FormatVersion {
    pub const V0: Self = Self(0);
    /// bun v0.0.x - bun v0.1.6
    pub const V1: Self = Self(1);
    /// bun v0.1.7+
    /// This change added tarball URLs to npm-resolved packages
    pub const V2: Self = Self(2);
    /// Changed semver major/minor/patch to each use u64 instead of u32
    pub const V3: Self = Self(3);

    pub const fn current() -> Self {
        FormatVersion::V3
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Drop (deinit)
// ────────────────────────────────────────────────────────────────────────────

// `deinit` only frees owned fields → handled by Drop on each field type.
// No explicit Drop impl needed.

// ────────────────────────────────────────────────────────────────────────────
// EqlSorter
// ────────────────────────────────────────────────────────────────────────────

pub(crate) struct EqlSorter<'a> {
    pub string_buf: &'a [u8],
    pub pkg_names: &'a [SemverString],
}

/// Basically placement id
#[derive(Clone, Copy)]
pub(crate) struct PathToId {
    pub pkg_id: PackageID,
    /// Borrows a `Box<[u8]>` parked in `tree_paths` for the duration of
    /// `Lockfile::eql` — `RawSlice` carries the outlives-holder invariant.
    pub tree_path: bun_ptr::RawSlice<u8>,
}

impl<'a> EqlSorter<'a> {
    pub(crate) fn order(&self, l: PathToId, r: PathToId) -> Ordering {
        let l_path = l.tree_path.slice();
        let r_path = r.tree_path.slice();
        // they exist in the same tree, name can't be the same so string compare.
        strings::order(l_path, r_path).then_with(|| {
            let l_name = self.pkg_names[l.pkg_id as usize];
            let r_name = self.pkg_names[r.pkg_id as usize];
            l_name.order(r_name, self.string_buf, self.string_buf)
        })
    }
}

impl Lockfile {
    /// `cut_off_pkg_id` should be removed when we stop appending packages to lockfile during install step
    pub fn eql(&self, r: &Lockfile, cut_off_pkg_id: usize) -> Result<bool, AllocError> {
        let l: &Lockfile = self;
        let l_hoisted_deps = l.buffers.hoisted_dependencies.as_slice();
        let r_hoisted_deps = r.buffers.hoisted_dependencies.as_slice();
        let l_string_buf = l.buffers.string_bytes.as_slice();
        let r_string_buf = r.buffers.string_bytes.as_slice();

        let l_len = l_hoisted_deps.len();
        let r_len = r_hoisted_deps.len();

        if l_len != r_len {
            return Ok(false);
        }

        let mut sort_buf: Vec<PathToId> = Vec::with_capacity(l_len + r_len);

        let mut path_buf = PathBuffer::uninit();
        let mut depth_buf: tree::DepthBuf = tree::depth_buf_uninit();

        // Track owned tree-path allocations so they outlive the sort and are freed at scope end.
        let mut tree_paths: Vec<Box<[u8]>> = Vec::new();

        for l_tree in l.buffers.trees.iter() {
            let (rel_path, _) = tree::relative_path_and_depth::<{ tree::IteratorPathStyle::PkgPath }>(
                l.buffers.trees.as_slice(),
                l.buffers.dependencies.as_slice(),
                l.buffers.string_bytes.as_slice(),
                l_tree.id,
                &mut path_buf,
                &mut depth_buf,
            );
            let tree_path: Box<[u8]> = Box::<[u8]>::from(rel_path.as_bytes());
            let tree_path_ptr = bun_ptr::RawSlice::new(&tree_path[..]);
            tree_paths.push(tree_path);
            for &l_dep_id in l_tree.dependencies.get(l_hoisted_deps) {
                if l_dep_id == invalid_dependency_id {
                    continue;
                }
                let l_pkg_id = l.buffers.resolutions[l_dep_id as usize];
                if l_pkg_id == invalid_package_id || l_pkg_id as usize >= cut_off_pkg_id {
                    continue;
                }
                sort_buf.push(PathToId {
                    pkg_id: l_pkg_id,
                    tree_path: tree_path_ptr,
                });
            }
        }
        let l_count = sort_buf.len();

        for r_tree in r.buffers.trees.iter() {
            let (rel_path, _) = tree::relative_path_and_depth::<{ tree::IteratorPathStyle::PkgPath }>(
                r.buffers.trees.as_slice(),
                r.buffers.dependencies.as_slice(),
                r.buffers.string_bytes.as_slice(),
                r_tree.id,
                &mut path_buf,
                &mut depth_buf,
            );
            let tree_path: Box<[u8]> = Box::<[u8]>::from(rel_path.as_bytes());
            let tree_path_ptr = bun_ptr::RawSlice::new(&tree_path[..]);
            tree_paths.push(tree_path);
            for &r_dep_id in r_tree.dependencies.get(r_hoisted_deps) {
                if r_dep_id == invalid_dependency_id {
                    continue;
                }
                let r_pkg_id = r.buffers.resolutions[r_dep_id as usize];
                if r_pkg_id == invalid_package_id || r_pkg_id as usize >= cut_off_pkg_id {
                    continue;
                }
                sort_buf.push(PathToId {
                    pkg_id: r_pkg_id,
                    tree_path: tree_path_ptr,
                });
            }
        }
        let (l_buf, r_buf) = sort_buf.split_at_mut(l_count);

        if l_buf.len() != r_buf.len() {
            return Ok(false);
        }

        let l_pkgs = l.packages.slice();
        let r_pkgs = r.packages.slice();
        let l_pkg_names = l_pkgs.items_name();
        let r_pkg_names = r_pkgs.items_name();

        {
            let sorter = EqlSorter {
                pkg_names: l_pkg_names,
                string_buf: l_string_buf,
            };
            l_buf.sort_unstable_by(|a, b| sorter.order(*a, *b));
        }

        {
            let sorter = EqlSorter {
                pkg_names: r_pkg_names,
                string_buf: r_string_buf,
            };
            r_buf.sort_unstable_by(|a, b| sorter.order(*a, *b));
        }

        let l_pkg_name_hashes = l_pkgs.items_name_hash();
        let l_pkg_resolutions = l_pkgs.items_resolution();
        let l_pkg_bins = l_pkgs.items_bin();
        let l_pkg_scripts = l_pkgs.items_scripts();
        let r_pkg_name_hashes = r_pkgs.items_name_hash();
        let r_pkg_resolutions = r_pkgs.items_resolution();
        let r_pkg_bins = r_pkgs.items_bin();
        let r_pkg_scripts = r_pkgs.items_scripts();

        let l_extern_strings = l.buffers.extern_strings.as_slice();
        let r_extern_strings = r.buffers.extern_strings.as_slice();

        debug_assert_eq!(l_buf.len(), r_buf.len());
        for (l_ids, r_ids) in l_buf.iter().zip(r_buf.iter()) {
            let l_pkg_id = l_ids.pkg_id as usize;
            let r_pkg_id = r_ids.pkg_id as usize;
            if l_pkg_name_hashes[l_pkg_id] != r_pkg_name_hashes[r_pkg_id] {
                return Ok(false);
            }
            let l_res = l_pkg_resolutions[l_pkg_id];
            let r_res = r_pkg_resolutions[r_pkg_id];

            if l_res.tag == ResolutionTag::Uninitialized
                || r_res.tag == ResolutionTag::Uninitialized
            {
                if l_res.tag != r_res.tag {
                    return Ok(false);
                }
            } else if !l_res.eql(&r_res, l_string_buf, r_string_buf) {
                return Ok(false);
            }

            if !crate::bin::Bin::eql(
                &l_pkg_bins[l_pkg_id],
                &r_pkg_bins[r_pkg_id],
                l_string_buf,
                l_extern_strings,
                r_string_buf,
                r_extern_strings,
            ) {
                return Ok(false);
            }

            if !package::Scripts::eql(
                &l_pkg_scripts[l_pkg_id],
                &r_pkg_scripts[r_pkg_id],
                l_string_buf,
                r_string_buf,
            ) {
                return Ok(false);
            }
        }

        Ok(true)
    }

    pub fn has_meta_hash_changed(
        &mut self,
        print_name_version_string: bool,
        packages_len: usize,
    ) -> Result<bool, BunError> {
        let previous_meta_hash = self.meta_hash;
        self.meta_hash = self.generate_meta_hash(print_name_version_string, packages_len)?;
        Ok(!strings::eql_long(
            &previous_meta_hash,
            &self.meta_hash,
            false,
        ))
    }

    pub fn generate_meta_hash(
        &self,
        print_name_version_string: bool,
        packages_len: usize,
    ) -> Result<MetaHash, BunError> {
        if packages_len <= 1 {
            return Ok(ZERO_HASH);
        }

        let mut string_builder = bun_core::StringBuilder::default();
        let names: &[SemverString] = &self.packages.items_name()[..packages_len];
        let resolutions: &[Resolution] = &self.packages.items_resolution()[..packages_len];
        let bytes = self.buffers.string_bytes.as_slice();
        let mut alphabetized_names: Vec<PackageID> = vec![0; packages_len.saturating_sub(1)];

        const HASH_PREFIX: &[u8] =
            b"\n-- BEGIN SHA512/256(`${alphabetize(name)}@${order(version)}`) --\n";
        const HASH_SUFFIX: &[u8] = b"-- END HASH--\n";
        string_builder.cap += HASH_PREFIX.len() + HASH_SUFFIX.len();
        {
            let mut i: usize = 1;

            while i + 16 < packages_len {
                for j in 0..16usize {
                    alphabetized_names[(i + j) - 1] = (i + j) as PackageID;
                    // posix path separators because we only use posix in the lockfile
                    string_builder.fmt_count(format_args!(
                        "{}@{}\n",
                        bstr::BStr::new(names[i + j].slice(bytes)),
                        resolutions[i + j].fmt(bytes, PathSep::Posix)
                    ));
                }
                i += 16;
            }

            while i < packages_len {
                alphabetized_names[i - 1] = i as PackageID;
                // posix path separators because we only use posix in the lockfile
                string_builder.fmt_count(format_args!(
                    "{}@{}\n",
                    bstr::BStr::new(names[i].slice(bytes)),
                    resolutions[i].fmt(bytes, PathSep::Posix)
                ));
                i += 1;
            }
        }

        const SCRIPTS_BEGIN: &[u8] = b"\n-- BEGIN SCRIPTS --\n";
        const SCRIPTS_END: &[u8] = b"\n-- END SCRIPTS --\n";
        let mut has_scripts = false;

        for (field_name, scripts) in self.scripts.fields() {
            for script in scripts.iter() {
                if !script.is_empty() {
                    string_builder.fmt_count(format_args!(
                        "{}: {}\n",
                        field_name,
                        bstr::BStr::new(script)
                    ));
                    has_scripts = true;
                }
            }
        }

        if has_scripts {
            string_builder.count(SCRIPTS_BEGIN);
            string_builder.count(SCRIPTS_END);
        }

        {
            let alphabetizer = package::Alphabetizer::<u64> {
                names: names.into(),
                buf: bytes.into(),
                resolutions: resolutions.into(),
            };
            alphabetized_names.sort_unstable_by(|a, b| alphabetizer.order(*a, *b));
        }

        string_builder.allocate().expect("unreachable");
        let _ = string_builder.append(HASH_PREFIX);

        for &i in alphabetized_names.iter() {
            let _ = string_builder.fmt(format_args!(
                "{}@{}\n",
                bstr::BStr::new(names[i as usize].slice(bytes)),
                resolutions[i as usize].fmt(bytes, PathSep::Any)
            ));
        }

        if has_scripts {
            let _ = string_builder.append(SCRIPTS_BEGIN);
            for (field_name, scripts) in self.scripts.fields() {
                for script in scripts.iter() {
                    if !script.is_empty() {
                        let _ = string_builder.fmt(format_args!(
                            "{}: {}\n",
                            field_name,
                            bstr::BStr::new(script)
                        ));
                    }
                }
            }
            let _ = string_builder.append(SCRIPTS_END);
        }

        let _ = string_builder.append(HASH_SUFFIX);

        let len = string_builder.len;
        let alphabetized_name_version_string = &string_builder.allocated_slice()[..len];
        if print_name_version_string {
            Output::flush();
            Output::disable_buffering();
            Output::writer()
                .write_all(alphabetized_name_version_string)
                .expect("unreachable");
            Output::enable_buffering();
        }

        let mut digest = ZERO_HASH;
        // SAFETY: engine is null (default).
        unsafe {
            Crypto::SHA512_256::hash(
                alphabetized_name_version_string,
                &mut digest,
                core::ptr::null_mut(),
            )
        };

        Ok(digest)
    }

    pub fn resolve_package_from_name_and_version(
        &self,
        package_name: &[u8],
        version: &DependencyVersion,
    ) -> Option<PackageID> {
        let name_hash = SemverStringBuilder::string_hash(package_name);
        let entry = self.package_index.get(&name_hash)?;
        let buf = self.buffers.string_bytes.as_slice();

        match version.tag {
            dependency::Tag::Npm => {
                // SAFETY: tag checked == .npm above; `npm` is the active
                // `dependency::Value` union field.
                let npm_group = &version.npm().version;
                // Only a resolution whose own tag is npm may be read through
                // `Resolution::npm()`: the root package, workspace members, and
                // folder/symlink deps share the name index with other variants.
                let satisfies = |resolution: &Resolution| -> bool {
                    resolution.tag == ResolutionTag::Npm
                        && npm_group.satisfies(resolution.npm().version, buf, buf)
                };
                match entry {
                    PackageIndexEntry::Id(id) => {
                        let resolutions = self.packages.items_resolution();

                        if cfg!(debug_assertions) {
                            debug_assert!((*id as usize) < resolutions.len());
                        }
                        if satisfies(&resolutions[*id as usize]) {
                            return Some(*id);
                        }
                    }
                    PackageIndexEntry::Ids(ids) => {
                        let resolutions = self.packages.items_resolution();

                        for &id in ids.iter() {
                            if cfg!(debug_assertions) {
                                debug_assert!((id as usize) < resolutions.len());
                            }
                            if satisfies(&resolutions[id as usize]) {
                                return Some(id);
                            }
                        }
                    }
                }
            }
            _ => {}
        }

        None
    }
}

// ────────────────────────────────────────────────────────────────────────────
// Default trusted dependencies
// ────────────────────────────────────────────────────────────────────────────

const MAX_DEFAULT_TRUSTED_DEPENDENCIES: usize = 512;

/// Sorted list of default trusted dependency names.
///
/// Embeds `default-trusted-dependencies.txt` with `include_str!` and builds
/// the sorted slice on first access. Kept alphabetical so `bun pm trusted
/// --default` need not re-sort.
pub static DEFAULT_TRUSTED_DEPENDENCIES_LIST: std::sync::LazyLock<Vec<&'static [u8]>> =
    std::sync::LazyLock::new(|| {
        const DATA: &str = include_str!("default-trusted-dependencies.txt");
        let mut names: Vec<&'static [u8]> = DATA
            .split([' ', '\r', '\n', '\t'])
            .filter(|s| !s.is_empty())
            .map(str::as_bytes)
            .collect();
        names.sort_unstable();
        debug_assert!(
            names.len() <= MAX_DEFAULT_TRUSTED_DEPENDENCIES,
            "default-trusted-dependencies.txt is too large, please increase \
             'MAX_DEFAULT_TRUSTED_DEPENDENCIES' in lockfile.rs"
        );
        names
    });

/// The default list of trusted dependencies is a static hashmap.
///
/// A `StaticHashMap` keyed by truncated-u32 string-hash, populated lazily on
/// first access. The hash is the truncated string hash so entries match
/// `Lockfile.trusted_dependencies` keys.
pub mod default_trusted_dependencies {
    use super::{
        DEFAULT_TRUSTED_DEPENDENCIES_LIST, MAX_DEFAULT_TRUSTED_DEPENDENCIES, SemverStringBuilder,
    };
    use bun_collections::static_hash_map::{
        Entry, HashContext, HashMapMixin, StaticHashMap, static_slots,
    };
    use std::sync::LazyLock;

    const SLOTS: usize = static_slots(MAX_DEFAULT_TRUSTED_DEPENDENCIES);

    pub(crate) struct TrustedDepHashCtx;
    impl HashContext<&'static [u8]> for TrustedDepHashCtx {
        #[inline]
        fn ctx_hash(s: &&'static [u8]) -> u64 {
            // truncate to u32 because Lockfile.trustedDependencies uses the same u32 string hash
            (SemverStringBuilder::string_hash(s) as u32) as u64
        }
        #[inline]
        fn ctx_eql(a: &&'static [u8], b: &&'static [u8]) -> bool {
            *a == *b
        }
    }

    type Map = StaticHashMap<
        &'static [u8],
        (),
        TrustedDepHashCtx,
        MAX_DEFAULT_TRUSTED_DEPENDENCIES,
        SLOTS,
    >;

    static MAP: LazyLock<Box<Map>> = LazyLock::new(|| {
        let mut map = Box::<Map>::default();
        for &dep in DEFAULT_TRUSTED_DEPENDENCIES_LIST.iter() {
            debug_assert!(map.len < MAX_DEFAULT_TRUSTED_DEPENDENCIES);
            let entry = map.get_or_put_assume_capacity(dep);
            debug_assert!(!entry.found_existing);
            *entry.value_ptr = ();
        }
        map
    });

    /// Iterate populated entries.
    pub(crate) fn entries() -> impl Iterator<Item = &'static Entry<&'static [u8], ()>> {
        MAP.entries.iter().filter(|e| !e.is_empty())
    }

    #[inline]
    pub(crate) fn has_with_hash(hash: u64) -> bool {
        MAP.has_with_hash(hash)
    }

    /// Open-coded `hasContext` so the lookup key can borrow with any lifetime,
    /// not just `'static`.
    pub(crate) fn has(name: &[u8]) -> bool {
        let hash = (SemverStringBuilder::string_hash(name) as u32) as u64;
        for entry in &MAP.entries[(hash >> MAP.shift) as usize..] {
            if entry.hash >= hash {
                return entry.hash == hash && entry.key == name;
            }
        }
        unreachable!()
    }
}

impl Lockfile {
    pub fn in_trusted_dependencies(&self, name: &[u8]) -> bool {
        let hash = SemverStringBuilder::string_hash(name) as u32;
        self.trusted_dependencies
            .as_ref()
            .is_some_and(|trusted| trusted.contains(&hash))
    }

    pub fn has_trusted_dependency(
        &self,
        alias: &[u8],
        pkg_name: &[u8],
        resolution: &Resolution,
    ) -> bool {
        if let Some(trusted_dependencies) = &self.trusted_dependencies {
            let trusted_name = if resolution.tag == ResolutionTag::Npm {
                pkg_name
            } else {
                alias
            };
            let hash = SemverStringBuilder::string_hash(trusted_name) as u32;
            let name_is_trusted = match trusted_dependencies.get(&hash) {
                Some(name) => !name.is_empty() && **name == *trusted_name,
                None => false,
            };
            if !name_is_trusted {
                return false;
            }
            if resolution.tag == ResolutionTag::Npm {
                return true;
            }
            return self.declared_by_root_or_workspace(alias, resolution);
        }

        // Only allow default trusted dependencies for npm packages. Check the
        // resolved package's real name, not the dependency alias, so an
        // `npm:`-aliased package can't inherit trust from a default-trusted
        // name.
        if resolution.tag != ResolutionTag::Npm || !default_trusted_dependencies::has(pkg_name) {
            return false;
        }

        let buf = self.buffers.string_bytes.as_slice();
        let npm = resolution.npm();
        let url = npm.url.slice(buf);
        if url.is_empty() {
            return true;
        }
        let registry = PackageManager::get()
            .scope_for_package_name(pkg_name)
            .url
            .href();
        let Ok(canonical_url) = crate::extract_tarball::build_url_with_printer(
            registry,
            &strings::StringOrTinyString::init(pkg_name),
            npm.version,
            buf,
            |args| -> Result<Vec<u8>, std::io::Error> {
                let mut out: Vec<u8> = Vec::new();
                out.write_fmt(args)?;
                Ok(out)
            },
        ) else {
            return false;
        };
        url == canonical_url.as_slice()
    }

    fn declared_by_root_or_workspace(&self, alias: &[u8], resolution: &Resolution) -> bool {
        let buf = self.buffers.string_bytes.as_slice();
        let packages = self.packages.slice();
        let resolutions = packages.items_resolution();
        let dependencies_lists = packages.items_dependencies();
        for (pkg_resolution, dependencies) in resolutions.iter().zip(dependencies_lists.iter()) {
            if pkg_resolution.tag != ResolutionTag::Workspace
                && pkg_resolution.tag != ResolutionTag::Root
            {
                continue;
            }
            for dep_id in dependencies.begin()..dependencies.end() {
                let dep = &self.buffers.dependencies[dep_id as usize];
                if dep.name.slice(buf) != alias {
                    continue;
                }
                let package_id = self.buffers.resolutions[dep_id as usize];
                if package_id == invalid_package_id || package_id as usize >= resolutions.len() {
                    continue;
                }
                if resolutions[package_id as usize].eql(resolution, buf, buf) {
                    return true;
                }
            }
        }

        false
    }
}

// ────────────────────────────────────────────────────────────────────────────
// PatchedDep
// ────────────────────────────────────────────────────────────────────────────

#[repr(C)]
#[derive(Clone, Copy)]
pub struct PatchedDep {
    /// e.g. "patches/is-even@1.0.0.patch"
    pub path: SemverString,
    _padding: [u8; 7],
    pub patchfile_hash_is_null: bool,
    /// the hash of the patch file contents
    __patchfile_hash: u64,
}

impl Default for PatchedDep {
    fn default() -> Self {
        PatchedDep {
            path: SemverString::default(),
            _padding: [0; 7],
            patchfile_hash_is_null: true,
            __patchfile_hash: 0,
        }
    }
}

impl PatchedDep {
    /// Construct with just `path` set. Exists because
    /// the explicit-padding / private-hash fields make the `..Default::default()`
    /// struct-update form unusable from sibling modules.
    pub fn with_path(path: SemverString) -> Self {
        Self {
            path,
            ..Default::default()
        }
    }

    pub fn set_patchfile_hash(&mut self, val: Option<u64>) {
        self.patchfile_hash_is_null = val.is_none();
        self.__patchfile_hash = val.unwrap_or(0);
    }

    pub fn patchfile_hash(&self) -> Option<u64> {
        if self.patchfile_hash_is_null {
            None
        } else {
            Some(self.__patchfile_hash)
        }
    }
}