@vltpkg/graph 1.0.0-rc.9 → 1.0.1

package/dist/{esm/ideal → ideal}/append-nodes.js

@@ -1,12 +1,14 @@
 import { joinDepIDTuple, joinExtra } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec';
+import { satisfies } from '@vltpkg/satisfies';
 import { longDependencyTypes, normalizeManifest } from '@vltpkg/types';
 import { fixupAddedNames } from "../fixup-added-names.js";
 import { shorten } from "../dependencies.js";
 import { removeOptionalSubgraph } from "../remove-optional-subgraph.js";
 import { extractNode } from "../reify/extract-node.js";
-import { endPeerPlacement, postPlacementPeerCheck, startPeerPlacement, } from "./peers.js";
+import { checkPeerEdgesCompatible, endPeerPlacement, forkPeerContext, postPlacementPeerCheck, startPeerPlacement, } from "./peers.js";
+import { compareByHasPeerDeps } from "./sorting.js";
 /**
  * Only install devDeps for git dependencies and importers
  * Everything else always gets installed
@@ -39,18 +41,96 @@ const getFileTypeInfo = (spec, fromNode, scurry) => {
     };
 };
 const isStringArray = (a) => Array.isArray(a) && !a.some(b => typeof b !== 'string');
+/**
+ * Try to find a compatible resolution for a dependency, checking peer context.
+ * If the first resolution candidate is incompatible with the peer context,
+ * try other candidates.
+ */
+const findCompatibleResolution = (spec, fromNode, graph, peerContext, queryModifier, _peer) => {
+    // Hoist invariants once
+    const fromLoc = fromNode.location;
+    const projectRoot = graph.projectRoot;
+    const monorepo = graph.monorepo;
+    const final = spec.final;
+    // Memoize satisfies() results per-node within this resolution attempt
+    const satisfiesCache = new Map();
+    const satisfiesFinal = (n) => {
+        const key = n.id;
+        const cached = satisfiesCache.get(key);
+        /* c8 ignore next 3 - optimization: cache hit when same node checked multiple times */
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = satisfies(key, final, fromLoc, projectRoot, monorepo);
+        satisfiesCache.set(key, result);
+        return result;
+    };
+    // Prefer existing edge target if it satisfies the spec.
+    // This ensures lockfile resolutions are preserved when still valid,
+    // rather than potentially picking a different satisfying version.
+    const existingEdge = fromNode.edgesOut.get(spec.name);
+    let existingNode;
+    if (existingEdge?.to &&
+        !existingEdge.to.detached &&
+        satisfiesFinal(existingEdge.to)) {
+        existingNode = existingEdge.to;
+    }
+    else {
+        existingNode = graph.findResolution(spec, fromNode, queryModifier);
+    }
+    let peerCompatResult = existingNode ?
+        checkPeerEdgesCompatible(existingNode, fromNode, peerContext, graph)
+        : { compatible: true };
+    // CANDIDATE FALLBACK: If first candidate is peer-incompatible, try others
+    // Lazy-load candidates only when fallback needed
+    if (existingNode && !peerCompatResult.compatible) {
+        const candidates = graph.nodesByName.get(final.name);
+        if (candidates && candidates.size > 1) {
+            for (const candidate of candidates) {
+                if (candidate === existingNode)
+                    continue;
+                if (candidate.detached)
+                    continue;
+                if (!satisfiesFinal(candidate))
+                    continue;
+                const compat = checkPeerEdgesCompatible(candidate, fromNode, peerContext, graph);
+                if (compat.compatible) {
+                    existingNode = candidate;
+                    peerCompatResult = compat;
+                    break;
+                }
+            }
+        }
+    }
+    return { existingNode, peerCompatResult };
+};
 /**
  * Fetch manifests for dependencies and create placement tasks.
+ *
+ * This is Phase 1 of the breadth-first graph building process. For each
+ * dependency at the current level:
+ * 1. Apply any active modifiers (spec swapping)
+ * 2. Try to find an existing node to reuse (with peer compatibility check)
+ * 3. If no reusable node, start a manifest fetch (in parallel)
+ * 4. Create placement tasks for Phase 2
+ *
+ * The result is sorted to process non-peer-dependent packages first,
+ * ensuring peer dependencies can resolve to already-placed siblings.
+ *
+ * **Read-only**: This function no longer mutates the graph. It returns
+ * tasks that will be applied serially in the BFS loop for deterministic ordering.
  */
 const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, peerContext, modifierRefs, depth = 0) => {
-    // Create fetch tasks for all dependencies at this level
     const fetchTasks = [];
     const placementTasks = [];
+    const reuseTasks = [];
+    const forkRequests = [];
     for (const { spec: originalSpec, type } of deps) {
         let spec = originalSpec;
         const fileTypeInfo = getFileTypeInfo(spec, fromNode, scurry);
         const activeModifier = modifierRefs?.get(spec.name);
-        // here is the place we swap specs if a edge modifier was defined
+        // MODIFIER HANDLING: Swap spec if an edge modifier is fully matched
+        // Example: `vlt install --override "react:^19"` changes react's spec
         const queryModifier = activeModifier?.modifier.query;
         const completeModifier = activeModifier &&
             activeModifier.interactiveBreadcrumb.current ===
@@ -59,30 +139,55 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
             completeModifier &&
             'spec' in activeModifier.modifier) {
             spec = activeModifier.modifier.spec;
+            // bareSpec of '-' means "remove this dependency"
             if (spec.bareSpec === '-') {
                 continue;
             }
         }
         const peer = type === 'peer' || type === 'peerOptional';
-        // skip reusing nodes for peer deps since their reusability
-        // is handled ahead-of-time during its parent's placement
-        const existingNode = graph.findResolution(spec, fromNode, queryModifier);
+        // NODE REUSE LOGIC with peer compatibility
+        const { existingNode, peerCompatResult } = findCompatibleResolution(spec, fromNode, graph, peerContext, queryModifier, peer);
+        // Accumulate fork request if incompatible peer edges detected (defer actual fork)
+        const effectivePeerContext = peerContext;
+        /* c8 ignore start */
+        if (!peerCompatResult.compatible && peerCompatResult.forkEntry) {
+            forkRequests.push(peerCompatResult.forkEntry);
+            // All fork entries from this fromNode will be applied together in Phase B
+        }
+        /* c8 ignore stop */
         // defines what nodes are eligible to be reused
         const validExistingNode = existingNode &&
             !existingNode.detached &&
-            // Regular deps can always reuse
+            // Regular deps can always reuse.
+            // Peer deps can reuse as well if their peer edges are compatible.
             /* c8 ignore start */
-            (!peer ||
-                // otherwise reusing peer deps only in case of a peerSetHash matche
-                existingNode.peerSetHash === fromNode.peerSetHash);
+            (!peer || peerCompatResult.compatible) &&
+            // Check if existing node's peer edges are compatible with new parent
+            peerCompatResult.compatible;
         /* c8 ignore stop */
         if (validExistingNode ||
-            // importers are handled at the ./add-nodes.ts top-level
+            // importers are handled at the ./refresh-ideal-graph.ts top-level
             // so we should just skip whenever we find one
             existingNode?.importer) {
-            graph.addEdge(type, spec, fromNode, existingNode);
+            // Defer edge creation to Phase B for deterministic ordering.
+            // Previously added immediately, but this caused race conditions when
+            // parallel fetches completed in different orders.
+            reuseTasks.push({ type, spec, fromNode, toNode: existingNode });
             continue;
         }
+        // workspace: specs can only resolve to local workspace packages.
+        // If we didn't find a matching workspace node above, it means either
+        // the workspace doesn't exist or its version doesn't satisfy the range.
+        if (spec.final.type === 'workspace') {
+            const wsVersion = graph.nodesByName
+                .get(spec.name)
+                ?.values()
+                .next().value?.version;
+            throw error(wsVersion ?
+                `workspace dependency ${spec} does not match the ` +
+                    `local workspace version (${wsVersion})`
+                : `no workspace found matching ${spec}`, { spec });
+        }
         // is the current edge pointint go an optional dependency?
         const edgeOptional = type === 'optional' || type === 'peerOptional';
         // Start manifest fetch immediately for parallel processing
@@ -90,7 +195,7 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
         // the "detached" node state means that it has already been load as
         // part of a graph (either lockfile or actual) and it has valid manifest
         // data so we shortcut the package info manifest fetch here
-        existingNode?.detached ?
+        existingNode?.detached && existingNode.manifest ?
             Promise.resolve(existingNode.manifest)
             // this is the entry point to fetch calls to retrieve manifests
             // from the build ideal graph point of view
@@ -114,7 +219,7 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
             edgeOptional,
             manifestPromise,
             depth,
-            peerContext,
+            peerContext: effectivePeerContext,
         };
         fetchTasks.push(fetchTask);
     }
@@ -130,34 +235,30 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
     // so that peer dependencies can easily reuse already placed regular
     // dependencies as part of peer context set resolution also makes sure to
     // sort by the manifest name for deterministic order.
-    placementTasks.sort((a, b) => {
-        const aIsPeer = (a.manifest?.peerDependencies &&
-            Object.keys(a.manifest.peerDependencies).length > 0) ?
-            1
-            : 0;
-        const bIsPeer = (b.manifest?.peerDependencies &&
-            Object.keys(b.manifest.peerDependencies).length > 0) ?
-            1
-            : 0;
-        // regular dependencies first, peer dependencies last
-        if (aIsPeer !== bIsPeer) {
-            return aIsPeer - bIsPeer;
-        }
-        // if both are in the same group,
-        // sort alphabetically by manifest name (fallback to spec.name)
-        const aName = a.manifest?.name /* c8 ignore next */ || a.fetchTask.spec.name;
-        const bName = b.manifest?.name || b.fetchTask.spec.name;
-        return aName.localeCompare(bName, 'en');
-    });
-    return placementTasks;
+    placementTasks.sort(compareByHasPeerDeps);
+    return { placementTasks, reuseTasks, forkRequests };
 };
 /**
- * Process placement tasks and collect child dependencies, this is the
- * second step of the appendNodes operation after manifest fetching in
- * which the final graph data structure is actually built.
+ * Process placement tasks and collect child dependencies.
+ *
+ * This is Phase 2 of the breadth-first graph building process. For each
+ * resolved manifest:
+ * 1. Handle missing manifests (optional vs required deps)
+ * 2. Start peer placement process (collect sibling context)
+ * 3. Place the node in the graph with appropriate flags
+ * 4. Trigger early extraction if eligible (performance optimization)
+ * 5. Collect child dependencies for the next BFS level
+ * 6. End peer placement (setup context update functions)
+ *
+ * Early extraction: When `actual` graph is provided, nodes destined for the
+ * vlt store are extracted immediately (in parallel) instead of waiting for
+ * the full ideal graph to be built. This significantly improves install time.
  */
 const processPlacementTasks = async (graph, options, placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove) => {
     const childDepsToProcess = [];
+    // Note: placementTasks are already sorted by fetchManifestsForDeps
+    // using compareByHasPeerDeps to ensure non-peer deps are processed first.
+    // We don't sort again here to preserve that ordering.
     for (const placementTask of placementTasks) {
         const { fetchTask, manifest } = placementTask;
         let { activeModifier, edgeOptional, fileTypeInfo, fromNode, peerContext, queryModifier, spec, type, } = fetchTask;
@@ -237,7 +338,13 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
         if (fileTypeInfo?.path && fileTypeInfo.isDirectory) {
             node.location = fileTypeInfo.path;
         }
-        node.setResolved();
+        // Do not clobber lockfile-provided resolved values.
+        // `setResolved()` cannot infer a tarball without a manifest,
+        // which can cause `resolved` to become undefined and the
+        // main lockfile to mutate across installs.
+        if (!node.resolved) {
+            node.setResolved();
+        }
         // collect child dependencies for processing in the next level
         const nextPeerDeps = new Map();
         // compute deps normally
@@ -254,7 +361,9 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
         for (const depTypeName of longDependencyTypes) {
             const depRecord = manifest[depTypeName];
             if (depRecord && shouldInstallDepType(node, depTypeName)) {
-                for (const [name, bareSpec] of Object.entries(depRecord)) {
+                // Sort Object.entries for deterministic iteration
+                const sortedEntries = Object.entries(depRecord).sort(([a], [b]) => a.localeCompare(b, 'en'));
+                for (const [name, bareSpec] of sortedEntries) {
                     // might need to skip already placed peer deps here
                     if (bundled.has(name))
                         continue;
@@ -262,7 +371,9 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
                         type: shorten(depTypeName, name, manifest),
                         spec: Spec.parse(name, bareSpec, {
                             ...options,
-                            registry: spec.registry,
+                            // git/file/remote parents have no spec.registry, so fall
+                            // back to the configured one. see vltpkg/vltpkg#1580.
+                            registry: spec.registry ?? options.registry,
                         }),
                     };
                     if (depTypeName === 'peerDependencies') {
@@ -324,22 +435,43 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
  * Append new nodes in the given `graph` for dependencies specified at `add`
  * and missing dependencies from the `deps` parameter.
  *
- * It also applies any modifiers that applies to a given node as it processes
- * and builds the graph.
+ * Uses **breadth-first traversal** (BFS) with **deterministic ordering** to
+ * ensure reproducible builds. The algorithm:
+ *
+ * 1. Process all deps at the current level in parallel
+ * 2. After each level, run `postPlacementPeerCheck` to handle peer contexts
+ * 3. Collect child deps for the next level
+ * 4. Repeat until no more deps to process
+ *
+ * **Peer Context Isolation**: Each workspace importer gets its own peer context
+ * to prevent cross-workspace leakage. Without this, `react@^18` from workspace A
+ * could incorrectly satisfy `react@^19` peer deps in workspace B.
+ *
+ * **Early Extraction**: When `actual` graph is provided, nodes are extracted
+ * to the vlt store during graph construction (not after), improving performance.
  */
 export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, options, seen, add, modifiers, modifierRefs, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove) => {
+    // Cycle detection: skip if already processed
     /* c8 ignore next */
     if (seen.has(fromNode.id))
         return;
     seen.add(fromNode.id);
-    // Get the initial peer context from the graph
-    const [initialPeerContext] = graph.peerContexts;
+    // PEER CONTEXT ISOLATION: Each workspace importer needs its own context
+    // to prevent peer targets from one workspace affecting another.
+    // The main importer (index 0) uses the initial context; others get fresh ones.
+    let initialPeerContext = graph.peerContexts[0];
     /* c8 ignore start - impossible */
-    if (!initialPeerContext) {
+    if (!initialPeerContext)
         throw error('no initial peer context found in graph');
-    }
     /* c8 ignore stop */
-    // Use a queue for breadth-first processing
+    if (fromNode.importer && fromNode !== graph.mainImporter) {
+        // Create isolated peer context for this workspace importer
+        const nextPeerContext = new Map();
+        nextPeerContext.index = graph.nextPeerContextIndex();
+        graph.peerContexts[nextPeerContext.index] = nextPeerContext;
+        initialPeerContext = nextPeerContext;
+    }
+    // BFS queue: process deps level by level for deterministic builds
     let currentLevelDeps = [
         {
             node: fromNode,
@@ -355,27 +487,78 @@ export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, op
             /* c8 ignore stop */
         },
     ];
+    // BFS MAIN LOOP: Process level by level until no more deps
     while (currentLevelDeps.length > 0) {
         const nextLevelDeps = [];
-        // Process all nodes at the current level in parallel
-        const levelResults = await Promise.all(currentLevelDeps.map(async ({ node, deps: nodeDeps, modifierRefs: nodeModifierRefs, peerContext, depth, }) => {
-            // Mark node as seen when we start processing its dependencies
+        // ============================================================
+        // PHASE A: PARALLEL FETCH (READ-ONLY)
+        // ============================================================
+        // Fetch all manifests at this level in parallel without mutating the graph.
+        // This phase is read-only to avoid race conditions from network timing.
+        const fetchResults = await Promise.all(currentLevelDeps.map(async ({ node, deps: nodeDeps, modifierRefs: nodeModifierRefs, peerContext, depth, }) => {
+            // Cycle prevention: mark as seen when starting to process
             seen.add(node.id);
-            // Fetch manifests for this node's dependencies
-            const placementTasks = await fetchManifestsForDeps(packageInfo, graph, node, 
-            // Sort dependencies by spec.name for deterministic ordering
+            // Fetch manifests and collect tasks (no graph mutations)
+            const result = await fetchManifestsForDeps(packageInfo, graph, node, 
+            // Sort by name for deterministic ordering (reproducible builds)
             nodeDeps.sort((a, b) => a.spec.name.localeCompare(b.spec.name, 'en')), scurry, peerContext, nodeModifierRefs, depth);
-            // Process the placement tasks and get child dependencies
-            return await processPlacementTasks(graph, options, placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove);
+            return {
+                entry: {
+                    node,
+                    deps: nodeDeps,
+                    modifierRefs: nodeModifierRefs,
+                    peerContext,
+                    depth,
+                },
+                result,
+            };
         }));
-        // Traverse the queued up children dependencies, adding and tracking
-        // dependencies on the peer context set, forking the context as needed
-        // and resolving any peer dependency that is able to be resolved using
-        // the current peer context set
+        // ============================================================
+        // PHASE B: SERIAL MUTATIONS (DETERMINISTIC ORDER)
+        // ============================================================
+        // Sort results by stable identifiers to ensure deterministic ordering
+        // regardless of which manifest fetch completed first
+        const sortedResults = fetchResults.sort((a, b) => {
+            // Sort by node ID (DepID-based, stable) and depth
+            const keyA = `${a.entry.node.id}::${a.entry.depth}`;
+            const keyB = `${b.entry.node.id}::${b.entry.depth}`;
+            return keyA.localeCompare(keyB, 'en');
+        });
+        // Apply all mutations serially in deterministic order
+        const levelResults = [];
+        for (const { entry, result } of sortedResults) {
+            // Apply accumulated fork requests if any (from Phase A deferred forks)
+            if (result.forkRequests.length > 0) {
+                const forkedContext = forkPeerContext(graph, entry.peerContext, result.forkRequests);
+                entry.peerContext = forkedContext;
+                // Update peer context in all placement tasks to use forked context
+                for (const task of result.placementTasks) {
+                    task.fetchTask.peerContext = forkedContext;
+                }
+            }
+            // Apply reuse edges in deterministic order (before placement)
+            // Sort reuse tasks by spec name for stability
+            const sortedReuseTasks = result.reuseTasks.sort((a, b) => a.spec.name.localeCompare(b.spec.name, 'en'));
+            for (const { type, spec, fromNode, toNode, } of sortedReuseTasks) {
+                graph.addEdge(type, spec, fromNode, toNode);
+            }
+            // Place nodes and collect child deps
+            const placed = await processPlacementTasks(graph, options, result.placementTasks, add, modifiers, scurry, packageInfo, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove);
+            levelResults.push(placed);
+        }
+        // ============================================================
+        // PHASE C: POST-PLACEMENT PEER CHECK
+        // ============================================================
+        // After all nodes at this level are placed, update peer contexts,
+        // fork as needed, and resolve peer deps that can be satisfied.
+        // This must happen AFTER placement so sibling nodes are available.
         postPlacementPeerCheck(graph, levelResults);
-        // Collect all child dependencies for the next level
+        // ============================================================
+        // STEP 3: COLLECT CHILD DEPS FOR NEXT LEVEL
+        // ============================================================
         for (const childDepsToProcess of levelResults) {
             for (const childDep of childDepsToProcess) {
+                // Skip already-seen nodes (cycle prevention)
                 if (!seen.has(childDep.node.id)) {
                     /* c8 ignore next */
                     const currentDepth = currentLevelDeps[0]?.depth ?? 0;
@@ -386,8 +569,7 @@ export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, op
                 }
             }
         }
-        // Move to the next level
+        // Advance to next BFS level
         currentLevelDeps = nextLevelDeps;
     }
 };
-//# sourceMappingURL=append-nodes.js.map

package/dist/{esm/ideal → ideal}/build-ideal-from-starting-graph.d.ts

@@ -12,4 +12,3 @@ export type BuildIdealFromStartingGraphOptions = RefreshIdealGraphOptions & {
  * listed in the `add` and `remove` properties.
  */
 export declare const buildIdealFromStartingGraph: (options: BuildIdealFromStartingGraphOptions) => Promise<Graph>;
-//# sourceMappingURL=build-ideal-from-starting-graph.d.ts.map

package/dist/{esm/ideal → ideal}/build-ideal-from-starting-graph.js

@@ -67,4 +67,3 @@ export const buildIdealFromStartingGraph = async (options) => {
     options.graph.gc();
     return options.graph;
 };
-//# sourceMappingURL=build-ideal-from-starting-graph.js.map

package/dist/{esm/ideal → ideal}/build.d.ts

@@ -38,4 +38,3 @@ export type BuildIdealOptions = LoadActualOptions & {
  * dependencies listed in the `add` and `remove` properties.
  */
 export declare const build: (options: BuildIdealOptions) => Promise<Graph>;
-//# sourceMappingURL=build.d.ts.map

package/dist/{esm/ideal → ideal}/build.js

@@ -39,7 +39,17 @@ export const build = async (options) => {
             monorepo,
         });
     }
-    catch {
+    catch (err) {
+        // Check if this is a lockfile version mismatch
+        const cause = err.cause;
+        if (cause?.code === 'ELOCKFILEVERSION') {
+            // If lockfile is from a different vlt version, hard fail
+            if (typeof cause.found === 'number' &&
+                typeof cause.wanted === 'number') {
+                throw err;
+            }
+            // TODO: add warning to CLI layer via @vltpkg/output when available
+        }
         graph = loadActual({
             ...options,
             mainManifest,
@@ -72,4 +82,3 @@ export const build = async (options) => {
     }
     return res;
 };
-//# sourceMappingURL=build.js.map

package/dist/{esm/ideal → ideal}/get-importer-specs.d.ts

@@ -18,4 +18,3 @@ export declare const getImporterSpecs: (options: GetImporterSpecsOptions) => {
     transientAdd: TransientAddMap;
     transientRemove: TransientRemoveMap;
 };
-//# sourceMappingURL=get-importer-specs.d.ts.map

package/dist/{esm/ideal → ideal}/get-importer-specs.js

@@ -49,8 +49,20 @@ export const getImporterSpecs = (options) => {
                 // skip if the edge exists and already uses the same spec
                 if (edge?.to && depSpec === edge.spec.bareSpec)
                     continue;
+                const spec = Spec.parse(depName, depSpec, options);
+                // if a workspace dep references a workspace that no longer exists
+                // (folder was removed), mark it for removal instead of trying to
+                // resolve it — the workspace can't be satisfied
+                if (spec.type === 'workspace' && !edge?.to) {
+                    const wsExists = [...graph.importers].some(n => n.name === depName);
+                    if (!wsExists) {
+                        removeDeps.add(depName);
+                        removeResult.modifiedDependencies = true;
+                        continue;
+                    }
+                }
                 const dependency = asDependency({
-                    spec: Spec.parse(depName, depSpec, options),
+                    spec,
                     type: shorten(depType, depName, importer.manifest),
                 });
                 addDeps.set(depName, dependency);
@@ -178,4 +190,3 @@ export const getImporterSpecs = (options) => {
         transientRemove,
     };
 };
-//# sourceMappingURL=get-importer-specs.js.map