Struct LockfileGraph 

pub struct LockfileGraph {

    pub importers: BTreeMap<String, Vec<DirectDep>>,
    pub packages: BTreeMap<String, LockedPackage>,
    pub settings: LockfileSettings,
    pub overrides: BTreeMap<String, String>,
    pub package_extensions_checksum: Option<String>,
    pub pnpmfile_checksum: Option<String>,
    pub ignored_optional_dependencies: BTreeSet<String>,
    pub times: BTreeMap<String, String>,
    pub skipped_optional_dependencies: BTreeMap<String, BTreeMap<String, String>>,
    pub catalogs: BTreeMap<String, BTreeMap<String, CatalogEntry>>,
    pub bun_config_version: Option<u32>,
    pub patched_dependencies: BTreeMap<String, String>,
    pub trusted_dependencies: Vec<String>,
    pub runtimes: BTreeMap<String, RuntimePin>,
    pub extra_fields: BTreeMap<String, Value>,
    pub workspace_extra_fields: BTreeMap<String, BTreeMap<String, Value>>,
}

Represents a resolved dependency graph from any lockfile format.

Fields

importers: BTreeMap<String, Vec<DirectDep>>

Direct dependencies of the root project (and workspace packages). Key: importer path (e.g., “.” for root), Value: list of (name, version) pairs.

packages: BTreeMap<String, LockedPackage>

All resolved packages.

settings: LockfileSettings

Per-graph settings that round-trip through the lockfile header (pnpm v9’s settings: block). Don’t affect graph structure; stamped into the YAML when writing and read back when parsing, so subsequent installs see the same resolution-mode state.

overrides: BTreeMap<String, String>

Dependency overrides recorded in pnpm-lock.yaml’s top-level overrides: block. Map of raw selector key → version specifier (or npm: alias). Keys are the user’s verbatim selector strings — bare name, foo>bar, foo@<2, **/foo, or any combination. Round-tripped so subsequent installs can detect override drift on a string-compare of the key+value without re-running the resolver. The resolver parses these into override_rule::OverrideRules at the start of each resolve pass.

package_extensions_checksum: Option<String>

pnpm’s top-level packageExtensionsChecksum: — a sha256- prefixed object-hash of the effective packageExtensions config. Lets pnpm detect that the extensions changed (and the graph must be re-resolved) without re-reading every manifest. None when there are no package extensions (pnpm omits the field). Only the pnpm reader/writer touches this; other formats leave it None. Computed via pnpm::package_extensions_checksum.

pnpmfile_checksum: Option<String>

pnpm’s top-level pnpmfileChecksum: — a sha256- prefixed hash of the local pnpmfile contents (CRLF-normalized). Lets pnpm detect that a .pnpmfile.cjs/.mjs hook changed without re-running it. None when no local pnpmfile participates (pnpm omits the field). pnpm-only, like package_extensions_checksum. Computed via pnpm::pnpmfile_checksum.

ignored_optional_dependencies: BTreeSet<String>

Names listed in the root manifest’s pnpm.ignoredOptionalDependencies. The resolver drops entries in this set from every optionalDependencies map before enqueueing, matching pnpm’s read-package hook. Round-tripped through pnpm-lock.yaml’s top-level ignoredOptionalDependencies: list so drift detection can notice when the user edits the field.

times: BTreeMap<String, String>

Per-package publish timestamps, keyed by canonical name@version (no peer suffix). Round-trips through pnpm-lock.yaml’s top-level time: block so --resolution-mode=time-based can compute a publishedBy cutoff from packages already in the lockfile without re-fetching packuments.

skipped_optional_dependencies: BTreeMap<String, BTreeMap<String, String>>

Optional dependencies the resolver intentionally skipped on the platform that wrote this lockfile (either filtered by os/cpu/libc, or named in pnpm.ignoredOptionalDependencies). Keyed by importer path, inner map is name → specifier captured from package.json at resolve time.

Drift detection uses this to distinguish “user just added a new optional dep” (which is real drift) from “this optional was already considered and consciously dropped on this platform” (which is not drift). Without it, every --frozen-lockfile install on a platform that skipped a fixture would hard-fail.

catalogs: BTreeMap<String, BTreeMap<String, CatalogEntry>>

Resolved catalog entries, mirroring pnpm v9’s top-level catalogs: block. Outer key is the catalog name (default for the unnamed catalog: field in pnpm-workspace.yaml); inner key is the package name. Each entry pairs the original specifier from the workspace catalog with the version the resolver chose for it. Round-tripped through the lockfile so drift detection can fire when a catalog spec changes without re-resolving.

bun_config_version: Option<u32>

bun’s top-level configVersion — a second format counter bun added alongside lockfileVersion to track its own config- schema changes. Only the bun parser/writer ever touches this; other formats leave it None. Round-tripping the parsed value keeps the writer from silently downgrading the field (e.g. from 2 back to 1) when bun bumps it in a future release.

patched_dependencies: BTreeMap<String, String>

Top-level patchedDependencies: block mirrored by bun 1.1+ and pnpm 9+. Key: selector (lodash@4.17.21), value: relative patch file path (patches/lodash@4.17.21.patch). Round-tripped verbatim so a parse/write cycle doesn’t silently drop user patches from the lockfile.

trusted_dependencies: Vec<String>

Top-level trustedDependencies: block (bun) — a package-name allowlist for lifecycle script execution. Preserved so re-emitting a bun.lock doesn’t strip the allowlist and cause subsequent installs to skip scripts the user explicitly approved.

Kept as a Vec (not a set) so bun’s original order round-trips byte-identically; bun emits the list in insertion order. The parser is responsible for deduping if the source lockfile carried a duplicate.

runtimes: BTreeMap<String, RuntimePin>

Pinned runtimes (pnpm 10.14+ devEngines.runtime recording), keyed by runtime name (node). pnpm models a pinned runtime as a synthetic importer dep whose specifier/version carry a runtime: prefix plus a packages: entry keyed <name>@runtime:<version> holding a variations resolution with one downloadable artifact per platform. aube lifts that encoding into this typed map on parse and re-emits the pnpm shape on write (aube-lock.yaml and pnpm-lock.yaml share the writer). Foreign formats (npm/yarn/bun) have no runtime shape: their parsers leave this empty and their writers skip it.

extra_fields: BTreeMap<String, Value>

Top-level lockfile fields that aren’t explicitly modeled on LockfileGraph. Populated by per-format parsers on best-effort basis so the writer can re-emit blocks a future lockfile version might add (or ones we haven’t promoted to typed fields yet) without silently stripping them on round-trip. Each parser/writer is responsible for emitting values in its format’s native serialization.

workspace_extra_fields: BTreeMap<String, BTreeMap<String, Value>>

Per-workspace-importer extras keyed by importer path ("" for root in bun, "." for others). Stores anything in the workspace entry the typed model doesn’t capture so a parse/ write cycle doesn’t drop fields the user (or bun) wrote there.

Implementations

impl LockfileGraph

pub fn check_drift( &self, manifest: &PackageJson, workspace_overrides: &BTreeMap<String, String>, workspace_ignored_optional: &[String], workspace_catalogs: &BTreeMap<String, BTreeMap<String, String>>, ) -> DriftStatus

Compare this lockfile’s root importer against a single manifest.

Mirrors pnpm’s prefer-frozen-lockfile check: a lockfile is “fresh” iff every direct dep specifier in package.json exactly matches the specifier recorded in the lockfile (string compare, not semver). Used to decide whether to skip resolution and trust the lockfile (Fresh) or fall back to a full re-resolve (Stale { reason }).

For workspace projects, use check_drift_workspace instead — this method only inspects the root importer.

workspace_overrides is the overrides: block from pnpm-workspace.yaml (pnpm v10 moved overrides there). Pass an empty map when the project has no workspace-yaml overrides. Keys are merged on top of manifest.overrides_map() before the drift comparison, matching the resolver’s effective-override set — otherwise a lockfile written with a workspace override immediately looks stale on the next --frozen-lockfile run.

workspace_ignored_optional is the same idea for pnpm-workspace.yaml’s ignoredOptionalDependencies block: the resolver unions it with the manifest’s list, so the drift check has to see the same union or a freshly-written lockfile immediately reads as stale.

workspace_catalogs is the catalog: / catalogs: block from pnpm-workspace.yaml. pnpm resolves catalog: references in override values against this map before writing the lockfile and before comparing on re-install, so both sides of the drift check have to see the catalog-resolved form — otherwise a "lodash": "catalog:" override reads as stale against a lockfile that recorded the resolved "lodash": "4.17.21".

Lockfile formats that don’t record specifiers (npm, yarn, bun) always return Fresh since we have no way to detect drift without re-resolving.

pub fn check_drift_for_kind( &self, manifest: &PackageJson, workspace_overrides: &BTreeMap<String, String>, workspace_ignored_optional: &[String], workspace_catalogs: &BTreeMap<String, BTreeMap<String, String>>, kind: LockfileKind, ) -> DriftStatus

pub fn check_drift_workspace( &self, manifests: &[(String, PackageJson)], workspace_overrides: &BTreeMap<String, String>, workspace_ignored_optional: &[String], workspace_catalogs: &BTreeMap<String, BTreeMap<String, String>>, is_workspace_install: bool, ) -> DriftStatus

Workspace-aware drift check.

Each entry in manifests is (importer_path, manifest) — for example (".", root_manifest), ("packages/app", app_manifest), .... Every importer is checked against its own manifest; the first stale importer determines the result.

See check_drift for the workspace_overrides contract.

pub fn check_drift_workspace_for_kind( &self, manifests: &[(String, PackageJson)], workspace_overrides: &BTreeMap<String, String>, workspace_ignored_optional: &[String], workspace_catalogs: &BTreeMap<String, BTreeMap<String, String>>, is_workspace_install: bool, kind: LockfileKind, ) -> DriftStatus

pub fn check_catalogs_drift( &self, workspace_catalogs: &BTreeMap<String, BTreeMap<String, String>>, ) -> DriftStatus

Compare this lockfile’s catalog snapshot against the current pnpm-workspace.yaml catalogs.

pnpm only writes catalog entries that at least one importer references — unused entries are absent from the lockfile. So “missing from lockfile” doesn’t mean “added by the user”, it means “declared but unreferenced”, which is not drift. The transition from unused → used is caught by the importer-level drift check, since a fresh catalog: reference shows up as a new dep in some package.json.

We fire on two cases only:

• the spec changed for an entry the lockfile already records (the entry is in use, and re-resolution must rerun);
• the workspace removed an entry that the lockfile records (the importer using catalog: now points at nothing).

Resolved versions are deliberately not part of the comparison — the version is an output of resolution, so a stale lockfile version is what re-resolution is supposed to fix. Drift only fires on user intent (the specifier).

impl LockfileGraph

pub fn root_deps(&self) -> &[DirectDep]

Get all direct dependencies of the root project.

pub fn get_package(&self, dep_path: &str) -> Option<&LockedPackage>

Get a package by its dep_path key.

pub fn filter_deps<F>(&self, keep: F) -> LockfileGraph

where F: Fn(&DirectDep) -> bool,

Produce a new LockfileGraph containing only the direct deps that match keep and the transitive deps reachable from them.

Used by install --prod to drop DepType::Dev roots and everything only reachable through them, and by install --no-optional for optional deps. The filter runs over every importer’s direct-dep list, so workspace projects behave correctly.

Packages that are reachable from a retained root through a transitive chain are kept even if a pruned dev dep also happened to depend on them — the check is “is this package reachable from any retained root?”, not “was this package introduced by a retained root?”.

pub fn subset_to_importer<F>( &self, importer_path: &str, keep: F, ) -> Option<LockfileGraph>

where F: Fn(&DirectDep) -> bool,

Produce a new LockfileGraph rooted at the importer at importer_path, with its transitive closure preserved and every other importer dropped. The retained importer is remapped to "." because the consumer installs the result as a standalone project.

Used by aube deploy: reading the source workspace lockfile and subsetting it to the deployed package lets a frozen install in the target reproduce the workspace’s exact versions without re-resolving against the registry. keep filters the importer’s direct deps the same way filter_deps does, so --prod / --dev / --no-optional deploys drop the matching roots.

Returns None if importer_path is not present in self.importers. Graph-wide metadata (settings, overrides, times, catalogs, ignored_optional_dependencies) is copied verbatim — structural pruning, not a resolution-mode reset. Callers targeting a non-workspace install may want to clear workspace-scope fields that would otherwise trigger drift detection against a rewritten target manifest.

pub fn overlay_metadata_from(&mut self, prior: &LockfileGraph)

Overlay per-package metadata fields from prior onto self for every (name, version) that survives in both graphs. Carries forward only fields the abbreviated packument (npm corgi) doesn’t ship — license, funding_url, and the bun-format configVersion — so a fresh re-resolve against the same spec set doesn’t lose them.

Keyed by canonical name@version, so a peer-context rewrite between the old and new graph still lines up. self’s own values win when set (fresh registry data is authoritative); prior’s fill in only the None / empty slots. Safe to call on any pair of graphs — parsing the old lockfile is the caller’s concern.

Trait Implementations

impl Clone for LockfileGraph

fn clone(&self) -> LockfileGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LockfileGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LockfileGraph

fn default() -> LockfileGraph

Returns the “default value” for a type.