@vltpkg/graph 0.0.0-9 → 1.0.0-rc.10

package/README.md

@@ -5,7 +5,44 @@
 This is the graph library responsible for representing the packages
 that are involved in a given install.
 
-**[API](#api)** · **[Usage](#usage)**
+**[Overview](#overview)** · **[Concepts](#concepts)** ·
+**[Architecture](#architecture)** · **[API](#api)** ·
+**[Usage](#usage)** · **[Related Workspaces](#related-workspaces)** ·
+**[References](#references)**
+
+## Overview
+
+The `@vltpkg/graph` workspace models a project's dependency
+relationships and drives npm-compatible installs by computing how
+`node_modules` should be structured. It exposes a public API through
+`src/index.ts` that re-exports core types and workflows.
+
+At a glance:
+
+- `Graph` encapsulates the full dependency graph for a project
+  (including monorepo workspaces), and is the source of truth for how
+  to lay out `node_modules`.
+- `Node` represents a unique package instance (uniqueness provided by
+  `@vltpkg/dep-id`).
+- `Edge` represents a dependency relationship from a dependent to a
+  dependency (eg. `dependencies`, `devDependencies`,
+  `peerDependencies`, etc.).
+- `Diff` describes the minimal set of changes required to transform an
+  Actual graph (disk) into an Ideal graph (desired outcome), which is
+  then applied by the `reify` subsystem.
+
+## Concepts
+
+- Importers: Root-level nodes used as starting points of the graph.
+  The `mainImporter` is the project root (its `package.json`), and the
+  remaining importers are workspaces discovered by
+  `@vltpkg/workspaces`.
+- Hidden Lockfile: A performance optimization stored at
+  `node_modules/.vlt-lock.json` mirroring the current on-disk state to
+  accelerate subsequent loads of the Actual graph.
+- Modifiers: Configuration for selectively altering dependency
+  resolution; Ideal/Actual builders support skipping node loads when
+  modifiers change.
 
 ## API
 
@@ -26,6 +63,13 @@ local file system.
 
 Loads the lockfile file found at `projectRoot` and returns the graph.
 
+### `reify(options): Promise<Diff>`
+
+Computes a `Diff` between the Actual and Ideal graphs and applies the
+minimal filesystem changes (creating/deleting links, writing
+lockfiles, hoisting, lifecycle scripts) to make the on-disk install
+match the Ideal graph.
+
 ## Usage
 
 Here's a quick example of how to use the `@vltpkg/graph.ideal.build`
@@ -37,3 +81,94 @@ import { ideal } from '@vltpkg/graph'
 
 const graph = await ideal.build({ projectRoot: process.cwd() })
 ```
+
+### Load Actual Graph and Reify
+
+```ts
+import { actual, ideal, reify } from '@vltpkg/graph'
+
+// Load current on-disk state
+const from = actual.load({
+  projectRoot: process.cwd(),
+  packageJson,
+  scurry,
+})
+
+// Build intended end state (may start from lockfile or actual)
+const to = await ideal.build({
+  projectRoot: process.cwd(),
+  packageInfo,
+  packageJson,
+  scurry,
+})
+
+// Apply minimal changes to match Ideal
+await reify({
+  graph: to,
+  actual: from,
+  packageInfo,
+  packageJson,
+  scurry,
+})
+```
+
+### Working With Lockfiles
+
+```ts
+import { lockfile } from '@vltpkg/graph'
+
+// Load virtual graph from vlt-lock.json
+const g = lockfile.load({
+  projectRoot,
+  mainManifest,
+  packageJson,
+  scurry,
+})
+
+// Save both lockfile formats
+lockfile.save({ graph: g, projectRoot, packageJson, scurry })
+```
+
+## Architecture
+
+Graph construction modes supported by the library:
+
+- Virtual Graphs (lockfile-based)
+  - Load and save via `src/lockfile/load.ts` and
+    `src/lockfile/save.ts`
+  - Hidden lockfile: `node_modules/.vlt-lock.json` for faster loads
+
+- Actual Graphs (filesystem-based)
+  - Loaded by traversing `node_modules` via `src/actual/load.ts`
+  - May shortcut to Hidden Lockfile if present and valid
+  - File layout changes are performed by `src/reify/`
+
+- Ideal Graphs (desired end state)
+  - Entry: `src/ideal/build.ts`
+  - Starts from Virtual (preferred) or falls back to Actual
+  - Merges `add`/`remove` input with importer manifests using
+    `src/ideal/get-importer-specs.ts`
+  - Fetches and expands manifests using `@vltpkg/package-info`, reuses
+    existing nodes that satisfy specs
+
+Finally, `src/diff.ts` computes changes and `src/reify/` applies them
+to the filesystem.
+
+## Related Workspaces
+
+- `@vltpkg/dep-id`: Unique IDs for packages, ensuring `Node` identity
+- `@vltpkg/spec`: Parse/normalize dependency specifiers and registry
+  semantics
+- `@vltpkg/semver`: Semantic version parsing/comparison
+- `@vltpkg/package-info`: Fetch remote manifests and artifacts
+  (registry, git, tarball)
+- `@vltpkg/package-json`: Read and cache local `package.json` files
+- `@vltpkg/workspaces`: Monorepo workspace discovery and grouping
+
+## References
+
+- package.json format and behavior:
+  [https://docs.npmjs.com/cli/v11/configuring-npm/package-json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json)
+- Semantic Versioning:
+  [https://semver.org/spec/v2.0.0.html](https://semver.org/spec/v2.0.0.html)
+- Monorepos: [https://monorepo.tools](https://monorepo.tools)

package/dist/esm/actual/load.d.ts

@@ -1,9 +1,12 @@
+import { Spec } from '@vltpkg/spec';
+import { Graph } from '../graph.ts';
+import type { DepID } from '@vltpkg/dep-id';
 import type { PackageJson } from '@vltpkg/package-json';
 import type { SpecOptions } from '@vltpkg/spec';
-import type { Manifest } from '@vltpkg/types';
+import type { NormalizedManifest } from '@vltpkg/types';
 import type { Monorepo } from '@vltpkg/workspaces';
 import type { Path, PathScurry } from 'path-scurry';
-import { Graph } from '../graph.ts';
+import type { GraphModifier } from '../modifiers.ts';
 export type LoadOptions = SpecOptions & {
     /**
      * The project root dirname.
@@ -12,7 +15,11 @@ export type LoadOptions = SpecOptions & {
     /**
      * The project root manifest.
      */
-    mainManifest?: Manifest;
+    mainManifest?: NormalizedManifest;
+    /**
+     * The graph modifiers helper object.
+     */
+    modifiers?: GraphModifier;
     /**
      * A {@link Monorepo} object, for managing workspaces
      */
@@ -39,12 +46,51 @@ export type LoadOptions = SpecOptions & {
      * hidden lockfile at `node_modules/.vlt-lock.json`
      */
     skipHiddenLockfile?: boolean;
+    /**
+     * Load only importers into the graph if the modifiers have changed.
+     */
+    skipLoadingNodesOnModifiersChange?: boolean;
+    /**
+     * If set to `true`, fail if lockfile is missing or out of date.
+     * Used by ci command to enforce lockfile integrity.
+     */
+    expectLockfile?: boolean;
+    /**
+     * If set to `true`, fail if lockfile is missing or out of sync with package.json.
+     * Prevents any lockfile modifications and is stricter than expectLockfile.
+     */
+    frozenLockfile?: boolean;
+    /**
+     * If set to `true`, only update the lockfile without performing any node_modules
+     * operations. Skips package extraction, filesystem operations, and hidden lockfile saves.
+     */
+    lockfileOnly?: boolean;
 };
 export type ReadEntry = {
     alias: string;
     name: string;
     realpath: Path;
 };
+/**
+ * The configuration object type as it is saved in the `.vlt/vlt.json`
+ */
+export type StoreConfigObject = {
+    modifiers: Record<string, string> | undefined;
+};
+/**
+ * Checks if a given object is a {@link StoreConfigObject}.
+ */
+export declare const isStoreConfigObject: (obj: unknown) => obj is StoreConfigObject;
+/**
+ * Returns a {@link StoreConfigObject} from a given object.
+ * Throws a TypeError if the object can't be converted.
+ */
+export declare const asStoreConfigObject: (obj: unknown) => StoreConfigObject;
+/**
+ * Returns a {@link DepID} for a given spec and path, if the spec is
+ * path-based or a registry spec, otherwise returns `undefined`.
+ */
+export declare const getPathBasedId: (spec: Spec, path: Path) => DepID | undefined;
 /**
  * Read the file system looking for `node_modules` folders and
  * returns a new {@link Graph} that represents the relationship

package/dist/esm/actual/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/actual/load.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGnD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAKnC,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACtC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAA;IACvB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IACxB;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;CACf,CAAA;AA6QD;;;;GAIG;AACH,eAAO,MAAM,IAAI,YAAa,WAAW,KAAG,KAwD3C,CAAA"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/actual/load.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAQnC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AAGxB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACtC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC;;OAEG;IACH,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IACxB;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;OAEG;IACH,iCAAiC,CAAC,EAAE,OAAO,CAAA;IAE3C;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;CACf,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,QACzB,OAAO,KACX,GAAG,IAAI,iBAGe,CAAA;AAEzB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACzB,OAAO,KACX,iBAKF,CAAA;AAUD;;;GAGG;AACH,eAAO,MAAM,cAAc,SACnB,IAAI,QACJ,IAAI,KACT,KAAK,GAAG,SAGQ,CAAA;AA2SnB;;;;GAIG;AACH,eAAO,MAAM,IAAI,YAAa,WAAW,KAAG,KAsG3C,CAAA"}

package/dist/esm/actual/load.js

@@ -1,15 +1,40 @@
-import { asDepID, hydrate, joinDepIDTuple } from '@vltpkg/dep-id';
+import { asDepID, hydrate, joinDepIDTuple, joinExtra, splitDepID, splitExtra, } from '@vltpkg/dep-id';
 import { Spec } from '@vltpkg/spec';
-import { longDependencyTypes } from '@vltpkg/types';
-import { shorten } from "../dependencies.js";
+import { graphStep } from '@vltpkg/output';
+import { isObject } from '@vltpkg/types';
+import { shorten, getRawDependencies, getDependencies, } from "../dependencies.js";
 import { Graph } from "../graph.js";
 import { loadHidden } from "../lockfile/load.js";
-import { graphStep } from '@vltpkg/output';
+import { saveHidden } from "../lockfile/save.js";
+import { readFileSync } from 'node:fs';
+/**
+ * Checks if a given object is a {@link StoreConfigObject}.
+ */
+export const isStoreConfigObject = (obj) => isObject(obj) &&
+    Object.prototype.hasOwnProperty.call(obj, 'modifiers') &&
+    isObject(obj.modifiers);
+/**
+ * Returns a {@link StoreConfigObject} from a given object.
+ * Throws a TypeError if the object can't be converted.
+ */
+export const asStoreConfigObject = (obj) => {
+    if (!isStoreConfigObject(obj)) {
+        throw new TypeError(`Expected a store config object, got ${obj}`);
+    }
+    return obj;
+};
+// path-based refer to the types of dependencies that are directly linked to
+// their real location in the file system and thus will not have an entry
+// in the `node_modules/.vlt` store
 const pathBasedType = new Set(['file', 'workspace']);
 const isPathBasedType = (type) => pathBasedType.has(type);
-const getPathBasedId = (spec, path) => isPathBasedType(spec.type) ?
-    joinDepIDTuple([spec.type, path])
-    : undefined;
+/**
+ * Returns a {@link DepID} for a given spec and path, if the spec is
+ * path-based or a registry spec, otherwise returns `undefined`.
+ */
+export const getPathBasedId = (spec, path) => isPathBasedType(spec.type) ?
+    joinDepIDTuple([spec.type, path.relativePosix()])
+    : findDepID(path);
 /**
  * Retrieve the {@link DepID} for a given package from its location.
  */
@@ -26,47 +51,25 @@ const findNodeModules = ({ parent, name, isCWD, }) => parent?.name === 'node_mod
  * Retrieves the scoped-normalized package name from its {@link Path}.
  */
 const findName = ({ parent, name }) => parent?.name.startsWith('@') ? `${parent.name}/${name}` : name;
-const isStringArray = (a) => Array.isArray(a) && !a.some(b => typeof b !== 'string');
-/*
- * Retrieves a map of all dependencies, of all types, that can be iterated
- * on and consulted when parsing the directory contents of the current node.
+/**
+ * Helper function that gets a modified {@link Spec} when finding a modifier
+ * that applies to a given dependency. Otherwise returns the original spec
+ * value and no queryModifier.
  */
-const getDeps = (node) => {
-    const dependencies = new Map();
-    const bundleDeps = node.manifest?.bundleDependencies ?? [];
-    // if it's an importer, bundleDeps are just normal. if it's a dep,
-    // then they're ignored entirely.
-    const bundled = (!node.importer &&
-        !node.id.startsWith('git') &&
-        isStringArray(bundleDeps)) ?
-        new Set(bundleDeps)
-        : new Set();
-    for (const depType of longDependencyTypes) {
-        const obj = node.manifest?.[depType];
-        // only care about devDeps for importers and git or symlink deps
-        // technically this will also include devDeps for tarball file: specs,
-        // but that is likely rare enough to not worry about too much.
-        if (depType === 'devDependencies' &&
-            !node.importer &&
-            !node.id.startsWith('git') &&
-            !node.id.startsWith('file')) {
-            continue;
-        }
-        if (obj) {
-            for (const [name, bareSpec] of Object.entries(obj)) {
-                // if it's a bundled dependency, we just ignore it entirely.
-                if (bundled.has(name))
-                    continue;
-                dependencies.set(name, {
-                    name,
-                    type: depType,
-                    bareSpec,
-                    registry: node.registry,
-                });
-            }
-        }
+const maybeApplyModifierToSpec = (spec, depName, modifierRefs) => {
+    const activeModifier = modifierRefs?.get(depName);
+    const queryModifier = activeModifier?.modifier.query;
+    const completeModifier = activeModifier &&
+        activeModifier.interactiveBreadcrumb.current ===
+            activeModifier.modifier.breadcrumb.last;
+    if (queryModifier &&
+        completeModifier &&
+        'spec' in activeModifier.modifier) {
+        const modifiedSpec = activeModifier.modifier.spec;
+        modifiedSpec.overridden = true;
+        return { spec: modifiedSpec, queryModifier };
     }
-    return dependencies;
+    return { spec, queryModifier };
 };
 /**
  * Reads the current directory defined at `currDir` and looks for folder
@@ -115,10 +118,14 @@ const readDir = (scurry, currDir, fromNodeName) => {
  * as dependencies of `fromNode`, building the instantiated `graph`.
  */
 const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, currDir) => {
-    const { loadManifests } = options;
-    const dependencies = getDeps(fromNode);
+    const { loadManifests, modifiers } = options;
+    const dependencies = getRawDependencies(fromNode);
     const seenDeps = new Set();
     const readItems = readDir(scurry, currDir, fromNode.name);
+    // Get modifier references for this node's dependencies
+    const modifierRefs = modifiers?.tryDependencies(fromNode, [
+        ...getDependencies(fromNode, options).values(),
+    ]);
     for (const { alias, name, realpath } of readItems) {
         let node;
         // tracks what dependencies have been seen
@@ -129,10 +136,17 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
         if (!loadManifests) {
             const depId = findDepID(realpath);
             if (depId) {
-                const h = hydrate(depId, alias, {
-                    ...options,
-                    registry: fromNode.registry,
-                });
+                let h = hydrate(depId, alias, options);
+                // if the parsed registry value is using the default value, then
+                // the node should inherit the registry value from its parent node
+                if (h.type === 'registry' &&
+                    h.registry === h.options.registry &&
+                    fromNode.registry) {
+                    h.registry = fromNode.registry;
+                }
+                // Check for active modifiers and replace spec even when not loading manifests
+                const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(h, alias, modifierRefs);
+                h = modifiedSpec;
                 // graphs build with no manifest have no notion of
                 // dependency types and or spec definitions since those
                 // would have to be parsed from a manifest
@@ -140,10 +154,12 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
                 h, // uses spec from hydrated id
                 {
                     name,
-                    ...(h.registrySpec ?
-                        { version: h.registrySpec } // adds version if available
-                        : null),
-                }, depId);
+                }, depId, joinExtra({ modifier: queryModifier }));
+                // Update active entry after placing package
+                const activeModifier = modifierRefs?.get(alias);
+                if (activeModifier && node) {
+                    modifiers?.updateActiveEntry(node, activeModifier);
+                }
             }
         }
         // retrieve references to the current folder name found in `fromNode`
@@ -161,12 +177,35 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
             const type = deps?.type || 'dependencies';
             const bareSpec = deps?.bareSpec || '*';
             const depType = shorten(type, alias, fromNode.manifest);
-            const spec = Spec.parse(alias, bareSpec, {
+            let spec = Spec.parse(alias, bareSpec, {
                 ...options,
                 registry: fromNode.registry,
             });
-            const maybeId = getPathBasedId(spec, realpath.relativePosix());
-            node = graph.placePackage(fromNode, depType, spec, mani, maybeId);
+            // Check for active modifiers and replace spec if a modifier is complete
+            const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, alias, modifierRefs);
+            spec = modifiedSpec;
+            const maybeId = getPathBasedId(spec, realpath);
+            let peerSetHash;
+            if (maybeId) {
+                // parses extra info from depID to retrieve peerSetHash
+                try {
+                    const tuple = splitDepID(maybeId);
+                    const type = tuple[0];
+                    const extra = type === 'registry' || type === 'git' ?
+                        tuple[3]
+                        : tuple[2];
+                    peerSetHash =
+                        extra ? splitExtra(extra).peerSetHash : undefined;
+                    /* c8 ignore next - impossible: getPathBasedId asserts valid dep id */
+                }
+                catch { }
+            }
+            node = graph.placePackage(fromNode, depType, spec, mani, maybeId, joinExtra({ modifier: queryModifier, peerSetHash }));
+            // Update active entry after placing package
+            const activeModifier = modifierRefs?.get(alias);
+            if (activeModifier && node) {
+                modifiers?.updateActiveEntry(node, activeModifier);
+            }
         }
         if (node) {
             // If a found dependency is not declared in any of the original
@@ -197,11 +236,14 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
     for (const { name, type, bareSpec } of dependencies.values()) {
         if (!seenDeps.has(name)) {
             const depType = shorten(type, name, fromNode.manifest);
-            const spec = Spec.parse(name, bareSpec, {
+            let spec = Spec.parse(name, bareSpec, {
                 ...options,
                 registry: fromNode.registry,
             });
-            graph.placePackage(fromNode, depType, spec);
+            // Check for active modifiers and replace spec for missing dependencies
+            const { spec: modifiedSpec, queryModifier } = maybeApplyModifierToSpec(spec, name, modifierRefs);
+            spec = modifiedSpec;
+            graph.placePackage(fromNode, depType, spec, undefined, undefined, joinExtra({ modifier: queryModifier }));
         }
     }
 };
@@ -212,34 +254,64 @@ const parseDir = (options, scurry, packageJson, depsFound, graph, fromNode, curr
  */
 export const load = (options) => {
     const done = graphStep('actual');
-    // TODO: once hidden lockfile is more reliable, default to false here
-    const { skipHiddenLockfile = true, projectRoot, packageJson, scurry, monorepo, } = options;
+    const { modifiers, monorepo, projectRoot, packageJson, scurry, skipHiddenLockfile = false, skipLoadingNodesOnModifiersChange = false, } = options;
     const mainManifest = options.mainManifest ?? packageJson.read(projectRoot);
     if (!skipHiddenLockfile) {
         try {
+            // if we reach here, the hidden lockfile is valid
             const graph = loadHidden({
+                ...options,
                 projectRoot,
                 mainManifest,
                 packageJson,
                 monorepo,
                 scurry,
             });
-            // TODO: check mtime of lockfile vs .vlt folder
+            done();
             return graph;
         }
-        catch { }
+        catch {
+            // if validation fails or any other error occurs,
+            // fall back to filesystem traversal
+        }
     }
     const graph = new Graph({ ...options, mainManifest });
-    const depsFound = new Map();
-    // starts the list of initial folders to parse using the importer nodes
-    for (const importer of graph.importers) {
-        depsFound.set(importer, scurry.cwd.resolve(`${importer.location}/node_modules`));
+    // retrieve the configuration object from the store
+    let storeConfig = { modifiers: undefined };
+    try {
+        storeConfig = asStoreConfigObject(JSON.parse(readFileSync(scurry.resolve('node_modules/.vlt/vlt.json'), 'utf8')));
     }
-    // breadth-first traversal of the file system tree reading deps found
-    // starting from the node_modules folder of every importer in order to
-    // find the actual installed dependencies at each location
-    for (const [node, path] of depsFound.entries()) {
-        parseDir(options, scurry, packageJson, depsFound, graph, node, path);
+    catch { }
+    const storeModifiers = JSON.stringify(storeConfig.modifiers ?? {});
+    const optionsModifiers = JSON.stringify(modifiers?.config);
+    const modifiersChanged = storeModifiers !== optionsModifiers;
+    const shouldLoadDependencies = !(skipLoadingNodesOnModifiersChange && modifiersChanged);
+    // will only skip loading dependencies if the
+    // skipLoadingNodesOnModifiersChange option is set to true
+    // and the current modifiers have not changed when compared
+    // to the modifiers stored in the `node_modules/.vlt/vlt.json` store config
+    if (shouldLoadDependencies) {
+        const depsFound = new Map();
+        // starts the list of initial folders to parse using the importer nodes
+        for (const importer of graph.importers) {
+            modifiers?.tryImporter(importer);
+            depsFound.set(importer, scurry.cwd.resolve(`${importer.location}/node_modules`));
+        }
+        // breadth-first traversal of the file system tree reading deps found
+        // starting from the node_modules folder of every importer in order to
+        // find the actual installed dependencies at each location
+        for (const [node, path] of depsFound.entries()) {
+            parseDir(options, scurry, packageJson, depsFound, graph, node, path);
+        }
+        // Clean up any pending modifier entries that were never completed
+        modifiers?.rollbackActiveEntries();
+        // caches the load result to the hidden lockfile when enabled
+        if (scurry.cwd.resolve('node_modules').lstatSync()?.isDirectory()) {
+            saveHidden({
+                ...options,
+                graph,
+            });
+        }
     }
     done();
     return graph;