@vltpkg/graph 1.0.7 → 1.0.9

package/dist/ideal/peers.js

@@ -3,7 +3,7 @@
 import { intersects } from '@vltpkg/semver';
 import { satisfies } from '@vltpkg/satisfies';
 import { Spec } from '@vltpkg/spec';
-import { getDependencies, shorten } from "../dependencies.js";
+import { getDependencies, shorten, shouldInstallDepType, } from "../dependencies.js";
 import { compareByType, getOrderedDependencies } from "./sorting.js";
 import { longDependencyTypes } from '@vltpkg/types';
 /**
@@ -29,15 +29,40 @@ const parseSpec = (name, bareSpec, fromNode, graph) => Spec.parse(name, bareSpec
     ...graph.mainImporter.options,
     registry: fromNode.registry ?? graph.mainImporter.options.registry,
 });
+/**
+ * Take private ownership of an entry's `specs` before writing to it: a
+ * fork shares the base's map until either side writes. Any other holder
+ * keeps `sharedSpecs` and clones on its own first write, so no refcount
+ * is needed.
+ */
+const ownSpecs = (entry) => {
+    if (entry.sharedSpecs) {
+        entry.specs = new Map(entry.specs);
+        entry.sharedSpecs = false;
+    }
+    return entry.specs;
+};
+/**
+ * Bump the base's revision: an entry was added, or an entry's target
+ * moved. Invalidates every fork key taken from it.
+ */
+const bumpRev = (peerContext) => {
+    peerContext.rev = (peerContext.rev ?? 0) + 1;
+};
 /**
  * Generate a unique cache key for a peer context fork operation.
  *
- * Format: `{baseIndex}::{sortedEntrySignatures}`
+ * Format: `{baseIndex}::{sortedEntrySignatures}::r{baseRev}`
  * - `baseIndex`: The parent context's index (0 for initial context)
  * - Entry signature: `{name}|{type}|{targetId}|{spec}` sorted alphabetically
+ * - `baseRev`: the base's revision, bumped on every mapping change
  *
  * This enables caching identical fork operations to avoid creating duplicate
  * peer contexts when the same entries would be added to the same base context.
+ * Forks snapshot the base's targets, so the base index alone is not enough:
+ * once a base target moves, an identical request must get a fresh fork
+ * instead of the snapshot taken before the move. The revision stands in for
+ * serialising the whole inherited mapping, which was O(context) per fork.
  */
 const getForkKey = (peerContext, entries) => {
     const base = peerContext.index ?? 0;
@@ -45,7 +70,7 @@ const getForkKey = (peerContext, entries) => {
         .map(e => `${e.spec.final.name}|${e.type}|${e.target?.id ?? '∅'}|${e.spec}`)
         .sort()
         .join(';');
-    return `${base}::${sig}`;
+    return `${base}::${sig}::r${peerContext.rev ?? 0}`;
 };
 /**
  * Check if parent declares a dep for peerName that the context target doesn't satisfy.
@@ -65,8 +90,12 @@ const shouldIgnoreContextMismatch = (peerName, contextTarget, fromNode, graph) =
     /* c8 ignore next - edge case: fromNode always has manifest in practice */
     if (!parentManifest)
         return false;
-    // Search all dependency types for a declaration of peerName
+    // Search all dependency types for a declaration of peerName. Only types
+    // the parent actually installs count: a registry parent's devDependencies
+    // are never placed, so they do not mean it resolves its own copy.
     for (const depType of longDependencyTypes) {
+        if (!shouldInstallDepType(fromNode, depType))
+            continue;
         const declared = parentManifest[depType]?.[peerName];
         if (!declared)
             continue;
@@ -100,6 +129,67 @@ const buildIncompatibleResult = (target, peerSpec, type, fromNode, graph) => {
     }
     return undefined;
 };
+/**
+ * Which node does `fromNode` (or its placement context) offer for
+ * `peerName`? Checked in the order `resolvePeerDeps` will use: the
+ * parent's own edge, then a dependency the parent declares but has not
+ * placed yet, then the context entry. Only targets satisfying `peerSpec`
+ * count.
+ */
+const findProvidedPeer = (peerName, peerSpec, fromNode, peerContext, parseOpts, satisfiesNodeSpec, pending) => {
+    const sibling = fromNode.edgesOut.get(peerName);
+    if (sibling?.to && satisfiesNodeSpec(sibling.to, peerSpec)) {
+        return { target: sibling.to, spec: peerSpec, type: sibling.type };
+    }
+    // what the parent is about to place at this level: it already reflects
+    // explicit adds and removes, transient deps and modifier swaps, none of
+    // which reach the manifest before reify. when given it is
+    // authoritative; the manifest is only consulted without it
+    let declared;
+    const pendingDep = pending?.get(peerName);
+    if (pendingDep) {
+        declared = { spec: pendingDep.spec, type: pendingDep.type };
+    }
+    else if (!pending && fromNode.manifest) {
+        const manifest = fromNode.manifest;
+        for (const depType of longDependencyTypes) {
+            if (!shouldInstallDepType(fromNode, depType))
+                continue;
+            const bare = manifest[depType]?.[peerName];
+            if (!bare)
+                continue;
+            const type = shorten(depType, peerName, manifest);
+            // the parent's own optional peer may never resolve; a required one
+            // is placed or resolved, so it does become the parent's edge
+            if (type === 'peerOptional')
+                continue;
+            declared = { spec: Spec.parse(peerName, bare, parseOpts), type };
+            break;
+        }
+    }
+    if (declared) {
+        // what the parent installs is decided by its own placement (existing
+        // edge, then lock, then findResolution), so no node is predicted
+        // here: a target-less fork entry lets the parent's live edge resolve
+        // the peer at the end of the level. disjoint ranges cannot both be
+        // satisfied, so there is nothing to fork for
+        const pf = declared.spec.final;
+        const sf = peerSpec.final;
+        if (pf.type === 'registry' &&
+            sf.type === 'registry' &&
+            pf.range &&
+            sf.range &&
+            !intersects(pf.range, sf.range)) {
+            return undefined;
+        }
+        return { spec: declared.spec, type: declared.type };
+    }
+    const entry = peerContext.get(peerName);
+    if (entry?.target && satisfiesNodeSpec(entry.target, peerSpec)) {
+        return { target: entry.target, spec: peerSpec, type: entry.type };
+    }
+    return undefined;
+};
 /**
  * Check if an existing node's peer edges would still resolve to the same
  * targets from a new parent's context. Returns incompatible info if any
@@ -118,7 +208,7 @@ const buildIncompatibleResult = (target, peerSpec, type, fromNode, graph) => {
  *    on the same package, and there's a graph node that would satisfy it but
  *    differs from what the existing node expects.
  */
-export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph) => {
+export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, graph, pending) => {
     const peerDeps = existingNode.manifest?.peerDependencies;
     // No peer deps = always compatible
     if (!peerDeps || Object.keys(peerDeps).length === 0) {
@@ -163,9 +253,27 @@ export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, gr
         if (existingEdge === undefined) {
             return { compatible: false };
         }
-        // Dangling peer edge (edge exists but unresolved) - skip, nothing to conflict with
-        if (!existingEdge.to)
+        // Dangling peer edge (edge exists but unresolved). An optional one
+        // means the copy was placed where nothing provided the peer: a parent
+        // that does provide it cannot share that copy, it has to fork so the
+        // peer gets linked. A dangling required peer is skipped as before.
+        if (!existingEdge.to) {
+            if (existingEdge.type === 'peerOptional') {
+                const provided = findProvidedPeer(peerName, Spec.parse(peerName, peerBareSpec, parseOpts), fromNode, peerContext, parseOpts, satisfiesNodeSpec, pending);
+                if (provided) {
+                    return {
+                        compatible: false,
+                        forkEntry: {
+                            spec: provided.spec,
+                            target: provided.target,
+                            type: provided.type,
+                        },
+                        keepVersion: true,
+                    };
+                }
+            }
             continue;
+        }
         const peerSpec = Spec.parse(peerName, peerBareSpec, parseOpts);
         // CHECK 1: Does peer context have a different target for this peer?
         const contextEntry = peerContext.get(peerName);
@@ -208,6 +316,8 @@ export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, gr
         let declaredType;
         if (manifest) {
             for (const depType of longDependencyTypes) {
+                if (!shouldInstallDepType(fromNode, depType))
+                    continue;
                 const deps = manifest[depType];
                 if (deps &&
                     typeof deps === 'object' &&
@@ -231,6 +341,8 @@ export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, gr
             const candidates = graph.nodesByName.get(peerName);
             if (candidates) {
                 for (const candidateNode of candidates) {
+                    if (candidateNode.detached)
+                        continue;
                     if (candidateNode.id !== existingEdge.to.id &&
                         satisfiesNodeSpec(candidateNode, parentSpec) &&
                         satisfiesNodeSpec(candidateNode, peerSpec)) {
@@ -254,10 +366,9 @@ export const checkPeerEdgesCompatible = (existingNode, fromNode, peerContext, gr
  * Retrieve a unique hash value for a given peer context set.
  */
 export const retrievePeerContextHash = (peerContext) => {
-    // skips creating the initial peer context ref
-    if (!peerContext?.index)
+    if (!peerContext)
         return undefined;
-    return `peer.${peerContext.index}`;
+    return `peer.${peerContext.index ?? 0}`;
 };
 /**
  * Generate a dedupe key for a spec stored in a peer context entry's
@@ -338,12 +449,19 @@ export const checkEntriesToPeerContext = (peerContext, entries) => {
  * peer context set. Extra info such as a target or dependent nodes is
  * optional.
  *
+ * When an entry gains a target that satisfies every spec collected so far,
+ * dependents of that entry are re-pointed at it only if their current target
+ * no longer satisfies one of those specs, so two equally valid resolutions
+ * never swap back and forth across rebuilds.
+ *
  * Returns true if forking is needed, false otherwise.
  */
 export const addEntriesToPeerContext = (peerContext, entries, fromNode, monorepo) => {
     // pre check for conflicts before processing
     if (checkEntriesToPeerContext(peerContext, entries))
         return true;
+    /** Does `node` satisfy every spec collected in `entry`? */
+    const satisfiesEntrySpecs = (node, entry, from) => [...entry.specs.values()].every(s => satisfies(node.id, s, from.location, from.projectRoot, monorepo));
     for (const { dependent, spec, target, type } of entries) {
         const name = target?.name ?? spec.final.name;
         let entry = peerContext.get(name);
@@ -357,6 +475,7 @@ export const addEntriesToPeerContext = (peerContext, entries, fromNode, monorepo
                 contextDependents: new Set(),
             };
             peerContext.set(name, entry);
+            bumpRev(peerContext);
             if (dependent)
                 entry.contextDependents.add(dependent);
             continue;
@@ -364,27 +483,41 @@ export const addEntriesToPeerContext = (peerContext, entries, fromNode, monorepo
         // check for sibling dep conflicts
         if (incompatibleSpecs(spec.final, entry))
             return true;
+        // collect the incoming spec before anything reads the entry: it
+        // constrains both the new target and any dependent kept on an older one
+        const specKey = peerSpecKey(spec);
+        if (!entry.specs.has(specKey))
+            ownSpecs(entry).set(specKey, spec);
         // update target if compatible with all specs
-        if (target &&
-            [...entry.specs.values()].every(s => satisfies(target.id, s, fromNode.location, fromNode.projectRoot, monorepo))) {
+        if (target && satisfiesEntrySpecs(target, entry, fromNode)) {
+            // two peer copies of the same version are the same resolution here:
+            // moving a dependent between them would only change its peer set
             if (target.id !== entry.target?.id &&
                 target.version !== entry.target?.version) {
-                // update dependents to point to new target
+                // re-point only dependents whose target this context has outgrown;
+                // one that still satisfies every spec is as valid as the new target,
+                // so a rebuild never swaps between two valid resolutions
                 for (const dep of entry.contextDependents) {
                     const edge = dep.edgesOut.get(name);
-                    if (edge?.to && edge.to !== target) {
-                        edge.to.edgesIn.delete(edge);
-                        edge.to = target;
-                        target.edgesIn.add(edge);
-                    }
+                    if (!edge?.to || edge.to === target)
+                        continue;
+                    if (satisfiesEntrySpecs(edge.to, entry, dep))
+                        continue;
+                    dep.graph.mutations++;
+                    edge.to.edgesIn.delete(edge);
+                    edge.to = target;
+                    target.edgesIn.add(edge);
                 }
                 entry.target = target;
+                bumpRev(peerContext);
+            }
+            else if (!entry.target) {
+                // only reachable when the branch above was skipped because
+                // target.version is undefined
+                entry.target = target;
+                bumpRev(peerContext);
             }
-            entry.target ??= target;
         }
-        const specKey = peerSpecKey(spec);
-        if (!entry.specs.has(specKey))
-            entry.specs.set(specKey, spec);
         if (dependent)
             entry.contextDependents.add(dependent);
     }
@@ -405,16 +538,24 @@ export const forkPeerContext = (graph, peerContext, entries) => {
     // register it in the graph
     graph.peerContexts[nextPeerContext.index] = nextPeerContext;
     graph.peerContextForkCache.set(forkKey, nextPeerContext);
-    // copy existing entries marking them as inactive, it's also important
-    // to note that specs and contextDependents are new objects so that changes
-    // to those in the new context do not affect the previous one
+    // copy existing entries marking them as inactive. specs are shared with
+    // the base until either side writes (both are flagged, so a base write
+    // after the fork cannot leak into it), but dependents are NOT inherited:
+    // they were placed in the parent context, so a target update in this
+    // fork must never re-point their edges.
+    // the target IS inherited: what a context resolves a name to must not
+    // depend on which fork a subtree happened to land in. it stays a
+    // snapshot (`getForkKey` invalidates it when the base moves) and is
+    // still guarded by `nodeSatisfiesSpec` at resolution time.
     for (const [name, entry] of peerContext.entries()) {
+        entry.sharedSpecs = true;
         nextPeerContext.set(name, {
             active: false,
-            specs: new Map(entry.specs),
-            target: undefined,
+            sharedSpecs: true,
+            specs: entry.specs,
+            target: entry.target,
             type: entry.type,
-            contextDependents: new Set(entry.contextDependents),
+            contextDependents: new Set(),
         });
     }
     // add the new entries to this peer context set, marking them as active
@@ -422,9 +563,20 @@ export const forkPeerContext = (graph, peerContext, entries) => {
     for (const entry of entries) {
         const { dependent, spec, target, type } = entry;
         const name = target?.name /* c8 ignore next */ ?? spec.final.name;
+        // a fork entry pointing the name at the node the base already
+        // resolved it to is the same resolution, so keep the constraints the
+        // base collected. dropping them leaves only this entry's (often wide)
+        // peer range, and CHECK 1's leniency then reads that as "any copy
+        // whose peer satisfies the range is fine", sharing a copy that is
+        // linked to a different node
+        const inherited = peerContext.get(name);
+        const specs = inherited?.target && inherited.target === target ?
+            new Map(inherited.specs)
+            : new Map();
+        specs.set(peerSpecKey(spec), spec);
         const newEntry = {
             active: true,
-            specs: new Map([[peerSpecKey(spec), spec]]),
+            specs,
             target,
             type,
             contextDependents: dependent ? new Set([dependent]) : new Set(),
@@ -598,12 +750,16 @@ export const endPeerPlacement = (peerContext, nextDeps, nextPeerDeps, graph, spe
             // These take priority because workspace's direct deps should win over
             // versions from other workspaces that may be in the peer context
             const siblingEntry = queuedEntries.find(e => (e.target?.name ?? e.spec.final.name) === name);
-            const siblingTarget = siblingEntry?.target ?? fromNode.edgesOut.get(name)?.to;
+            // prefer the parent's live edge target over the queued snapshot:
+            // the snapshot is captured at placement time and may be stale if a
+            // peer context target update has since re-pointed the parent's edge
+            const siblingTarget = fromNode.edgesOut.get(name)?.to ?? siblingEntry?.target;
             if (siblingTarget &&
                 nodeSatisfiesSpec(siblingTarget, spec, fromNode, graph)) {
                 // Override existing edge if pointing elsewhere (sibling must win)
                 const existingEdge = node.edgesOut.get(name);
                 if (existingEdge?.to && existingEdge.to !== siblingTarget) {
+                    graph.mutations++;
                     existingEdge.to.edgesIn.delete(existingEdge);
                     existingEdge.to = siblingTarget;
                     siblingTarget.edgesIn.add(existingEdge);
@@ -628,7 +784,7 @@ export const endPeerPlacement = (peerContext, nextDeps, nextPeerDeps, graph, spe
                 graph.addEdge(type, spec, node, entry.target);
                 const finalKey = peerSpecKey(spec.final);
                 if (!entry.specs.has(finalKey)) {
-                    entry.specs.set(finalKey, spec.final);
+                    ownSpecs(entry).set(finalKey, spec.final);
                 }
                 continue;
             }

package/dist/ideal/refresh-ideal-graph.d.ts

@@ -2,7 +2,7 @@ import type { PathScurry } from 'path-scurry';
 import type { PackageInfoClient } from '@vltpkg/package-info';
 import type { SpecOptions } from '@vltpkg/spec';
 import type { RollbackRemove } from '@vltpkg/rollback-remove';
-import type { BuildIdealAddOptions, BuildIdealFromGraphOptions, BuildIdealRemoveOptions, TransientAddMap, TransientRemoveMap } from './types.ts';
+import type { BuildIdealAddOptions, BuildIdealFromGraphOptions, BuildIdealRemoveOptions, ExplicitAddMap, TransientAddMap, TransientRemoveMap } from './types.ts';
 import type { GraphModifier } from '../modifiers.ts';
 import type { Graph } from '../graph.ts';
 export type RefreshIdealGraphOptions = BuildIdealAddOptions & BuildIdealRemoveOptions & BuildIdealFromGraphOptions & SpecOptions & {
@@ -26,6 +26,11 @@ export type RefreshIdealGraphOptions = BuildIdealAddOptions & BuildIdealRemoveOp
      * A {@link RollbackRemove} instance to handle extraction rollbacks
      */
     remover: RollbackRemove;
+    /**
+     * Dependency names that came from an explicit user request, keyed by
+     * the id of the node receiving them.
+     */
+    explicit?: ExplicitAddMap;
     /**
      * Dependencies to be added to non-importer nodes when they are placed.
      * Used for nested folder dependencies that are not importers.
@@ -36,8 +41,12 @@ export type RefreshIdealGraphOptions = BuildIdealAddOptions & BuildIdealRemoveOp
      * Used for nested folder dependencies that are not importers.
      */
     transientRemove?: TransientRemoveMap;
+    /**
+     * Only the lockfile is being written, so nothing is extracted.
+     */
+    lockfileOnly?: boolean;
 };
 /**
  * Rebuilds the provided ideal graph.
  */
-export declare const refreshIdealGraph: ({ add, graph, modifiers, packageInfo, scurry, actual, remove, remover, transientAdd, transientRemove, ...specOptions }: RefreshIdealGraphOptions) => Promise<void>;
+export declare const refreshIdealGraph: ({ add, graph, modifiers, packageInfo, scurry, actual, explicit, remove, remover, transientAdd, transientRemove, lockfileOnly, ...specOptions }: RefreshIdealGraphOptions) => Promise<void>;

package/dist/ideal/refresh-ideal-graph.js

@@ -1,5 +1,6 @@
 import { appendNodes } from "./append-nodes.js";
 import { compareByHasPeerDeps, getNodeOrderedDependencies, } from "./sorting.js";
+import { baseDepID } from '@vltpkg/dep-id';
 /**
  * Returns an ordered list of importer nodes.
  */
@@ -18,12 +19,25 @@ const getOrderedImporters = (graph) => {
 /**
  * Rebuilds the provided ideal graph.
  */
-export const refreshIdealGraph = async ({ add, graph, modifiers, packageInfo, scurry, actual, remove, remover, transientAdd, transientRemove, ...specOptions }) => {
+export const refreshIdealGraph = async ({ add, graph, modifiers, packageInfo, scurry, actual, explicit, remove, remover, transientAdd, transientRemove, lockfileOnly, ...specOptions }) => {
     const seen = new Set();
-    const extractPromises = [];
+    // early extraction only warms the store for the reify that follows;
+    // a lockfile-only run has none, and the next install re-extracts
+    // everything anyway since it never wrote a hidden lockfile
+    const extractPromises = lockfileOnly ? undefined : [];
     const seenExtracted = new Set();
     // gets an ordered list of importers to ensure deterministic processing
     const orderedImporters = getOrderedImporters(graph);
+    // importer edge spec text as the starting graph had it. a rebuild that
+    // only changes the text (`vlt i foo@1.2.3` over a `foo@^1.2.3` edge)
+    // produces no node diff, so reify has to be told the lockfile on disk
+    // no longer describes the graph
+    const specTexts = new Map();
+    for (const importer of graph.importers) {
+        for (const [name, edge] of importer.edgesOut) {
+            specTexts.set(`${importer.id}\0${name}`, edge.spec.bareSpec);
+        }
+    }
     const depsPerImporter = new Map();
     for (const importer of orderedImporters) {
         // gets an ordered list of dependencies for this importer
@@ -35,7 +49,41 @@ export const refreshIdealGraph = async ({ add, graph, modifiers, packageInfo, sc
     if (add.modifiedDependencies ||
         remove.modifiedDependencies ||
         graph.optionsChanged) {
+        const locked = new Map();
+        const ambiguous = new Set();
+        const record = (key, id) => {
+            if (ambiguous.has(key))
+                return;
+            const prev = locked.get(key);
+            if (prev === undefined) {
+                locked.set(key, id);
+            }
+            else if (prev !== id) {
+                // two peer copies of the same base resolve the name differently;
+                // a base-keyed lookup would be a guess, so drop the key
+                locked.delete(key);
+                ambiguous.add(key);
+            }
+        };
+        for (const edge of graph.edges) {
+            if (!edge.to)
+                continue;
+            record(`${edge.from.id}\0${edge.spec.name}`, edge.to.id);
+            // peer-fork rebuilds mint provisional `peer.N` parent ids that miss
+            // the canonical `peer.<hash>` keys captured here, so also key by
+            // the base id when that is unambiguous across peer copies
+            const base = baseDepID(edge.from.id);
+            if (base !== edge.from.id) {
+                record(`${base}\0${edge.spec.name}`, edge.to.id);
+            }
+        }
+        graph.lockedResolutions = locked;
         graph.resetEdges();
+        // the options block on disk no longer matches the config this graph
+        // was built with, so the lockfile has to be written even when the
+        // rebuild lands on the same nodes and edges
+        if (graph.optionsChanged)
+            graph.lockfileStale = true;
     }
     // iterates on the list of dependencies per importer updating
     // the graph using metadata fetch from the registry manifest files
@@ -51,14 +99,24 @@ export const refreshIdealGraph = async ({ add, graph, modifiers, packageInfo, sc
         const modifierRefs = modifiers?.tryDependencies(importer, deps);
         // Add new nodes for packages defined in the dependencies list fetching
         // metadata from the registry manifests and updating the graph
-        await appendNodes(packageInfo, graph, importer, deps, scurry, specOptions, seen, addedDeps, modifiers, modifierRefs, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove);
+        await appendNodes(packageInfo, graph, importer, deps, scurry, specOptions, seen, addedDeps, modifiers, modifierRefs, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove, explicit);
+    }
+    // locked resolutions only apply to the rebuild that captured them
+    graph.lockedResolutions = undefined;
+    for (const importer of graph.importers) {
+        for (const [name, edge] of importer.edgesOut) {
+            if (specTexts.get(`${importer.id}\0${name}`) !==
+                edge.spec.bareSpec) {
+                graph.lockfileStale = true;
+            }
+        }
     }
     // set default node locations, if possible
     for (const node of graph.nodes.values()) {
         node.setDefaultLocation();
     }
     // Wait for all extraction promises to complete
-    if (extractPromises.length > 0) {
+    if (extractPromises?.length) {
         await Promise.all(extractPromises);
     }
 };

package/dist/ideal/remove-satisfied-specs.d.ts

@@ -1,7 +1,16 @@
+import type { Edge } from '../edge.ts';
+import type { Dependency } from '../dependencies.ts';
 import type { BuildIdealAddOptions, BuildIdealFromGraphOptions } from './types.ts';
-export type RemoveSatisfiedSpecsOptions = BuildIdealAddOptions & BuildIdealFromGraphOptions;
+import type { GraphModifier } from '../modifiers.ts';
+export type RemoveSatisfiedSpecsOptions = BuildIdealAddOptions & BuildIdealFromGraphOptions & {
+    modifiers?: GraphModifier;
+};
 /**
  * Traverse the objects defined in `add` and removes any references to specs
  * that are already satisfied by the contents of the actual `graph`.
+ *
+ * Returns the satisfied edges whose spec text or dependency type differs
+ * from the one they were pruned against, e.g. a lockfile edge reading
+ * `peer latest` where `package.json` reads `devDependencies: ^1.2.3`.
  */
-export declare const removeSatisfiedSpecs: ({ add, graph, }: RemoveSatisfiedSpecsOptions) => void;
+export declare const removeSatisfiedSpecs: ({ add, graph, modifiers, }: RemoveSatisfiedSpecsOptions) => Map<Edge, Dependency>;

package/dist/ideal/remove-satisfied-specs.js

@@ -3,8 +3,13 @@ import { satisfies } from '@vltpkg/satisfies';
 /**
  * Traverse the objects defined in `add` and removes any references to specs
  * that are already satisfied by the contents of the actual `graph`.
+ *
+ * Returns the satisfied edges whose spec text or dependency type differs
+ * from the one they were pruned against, e.g. a lockfile edge reading
+ * `peer latest` where `package.json` reads `devDependencies: ^1.2.3`.
  */
-export const removeSatisfiedSpecs = ({ add, graph, }) => {
+export const removeSatisfiedSpecs = ({ add, graph, modifiers, }) => {
+    const staleSpecs = new Map();
     for (const [depID, dependencies] of add.entries()) {
         const importer = graph.nodes.get(depID);
         if (!importer) {
@@ -29,6 +34,17 @@ export const removeSatisfiedSpecs = ({ add, graph, }) => {
             // If the current graph edge is already valid, then we remove that
             // dependency item from the list of items to be added to the graph
             if (satisfies(edge.to?.id, dependency.spec, edge.from.location, graph.projectRoot, graph.monorepo)) {
+                // a governed edge carries the modifier value by construction:
+                // healing it to the manifest text would only be undone by the
+                // rebuild that re-applies the override. `implicit` is not a real
+                // edge type, it means "keep what the edge already is", so it
+                // never makes an edge stale
+                if ((edge.spec.bareSpec !== dependency.spec.bareSpec ||
+                    (dependency.type !== 'implicit' &&
+                        edge.type !== dependency.type)) &&
+                    !modifiers?.targetsImporterEdge(importer, dependency.spec)) {
+                    staleSpecs.set(edge, dependency);
+                }
                 dependencies.delete(name);
             }
         }
@@ -39,4 +55,5 @@ export const removeSatisfiedSpecs = ({ add, graph, }) => {
             add.delete(depID);
         }
     }
+    return staleSpecs;
 };

package/dist/ideal/types.d.ts

@@ -1,3 +1,4 @@
+import type { DepID } from '@vltpkg/dep-id';
 import type { PackageInfoClient } from '@vltpkg/package-info';
 import type { Spec } from '@vltpkg/spec';
 import type { DependencySaveType } from '@vltpkg/types';
@@ -18,6 +19,13 @@ export type TransientAddMap = Omit<AddImportersDependenciesMap, 'modifiedDepende
  * When these nodes are processed, their dependencies in this map are excluded.
  */
 export type TransientRemoveMap = Omit<RemoveImportersDependenciesMap, 'modifiedDependencies'>;
+/**
+ * Dependency names the user asked for on the command line, keyed by the
+ * {@link DepID} of the node receiving them. Snapshotted before
+ * manifest-derived deltas are merged into `add`, so it is the only
+ * reliable signal that a spec came from an explicit request.
+ */
+export type ExplicitAddMap = Map<DepID, Set<string>>;
 export type BuildIdealAddOptions = {
     /**
      * A {@link AddImportersDependenciesMap} in which keys are {@link DepID}
@@ -87,6 +95,11 @@ export type PeerContextEntry = {
      * instead of piling up per dependent.
      */
     specs: Map<string, Spec>;
+    /**
+     * `specs` is shared with the entry this one was forked from or into.
+     * Write through `ownSpecs()` so the other side keeps its snapshot.
+     */
+    sharedSpecs?: boolean;
     /** The target Node that satisfies all specs for this peer context entry */
     target: Node | undefined;
     /** The type of dependency this entry represents */
@@ -108,4 +121,11 @@ export type PeerContextEntryInput = {
  */
 export type PeerContext = Map<string, PeerContextEntry> & {
     index?: number;
+    /**
+     * Bumped whenever an entry is added or an entry's target changes, i.e.
+     * whenever the name -> target mapping a fork snapshots moves. Part of
+     * the fork cache key so a base that moved cannot hand out the fork
+     * taken before the move.
+     */
+    rev?: number;
 };