@vltpkg/graph 1.0.7 → 1.0.8

package/dist/ideal/append-nodes.js

@@ -1,22 +1,16 @@
-import { joinDepIDTuple, joinExtra } from '@vltpkg/dep-id';
+import { baseDepID, getTuple, hydrate, joinDepIDTuple, joinExtra, splitDepID, } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { Spec } from '@vltpkg/spec';
 import { satisfies } from '@vltpkg/satisfies';
+import { parse as parseVersion } from '@vltpkg/semver';
 import { longDependencyTypes, normalizeManifest } from '@vltpkg/types';
 import { fixupAddedNames } from "../fixup-added-names.js";
-import { shorten } from "../dependencies.js";
+import { addKey, shorten, shouldInstallDepType, } from "../dependencies.js";
 import { removeOptionalSubgraph } from "../remove-optional-subgraph.js";
 import { isPathSecurityError } from "../path-security-error.js";
 import { extractNode } from "../reify/extract-node.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
- */
-const shouldInstallDepType = (node, depType) => depType !== 'devDependencies' ||
-    node.importer ||
-    node.id.startsWith('git');
 /**
  * Retrieve the {@link DepID} and location for a `file:` type {@link Node}.
  */
@@ -42,61 +36,99 @@ const getFileTypeInfo = (spec, fromNode, scurry) => {
     };
 };
 const isStringArray = (a) => Array.isArray(a) && !a.some(b => typeof b !== 'string');
+const actualBases = new WeakMap();
+const hasActualBase = (actual, id) => {
+    let bases = actualBases.get(actual);
+    if (!bases) {
+        bases = new Set([...actual.nodes.keys()].map(baseDepID));
+        actualBases.set(actual, bases);
+    }
+    return bases.has(baseDepID(id));
+};
+/**
+ * Can the lockfile target still serve this spec? Exact for sources
+ * satisfies() understands; loose fallback for sources it cannot verify
+ * (named jsr registries, dist-tags): only for a registry node stamped
+ * with the same type+registry segments a fresh node for this spec would
+ * get, so a locked node from another source is never reused.
+ */
+const lockedFits = (n, spec, fromNode, graph) => {
+    const final = spec.final;
+    if (satisfies(n.id, final, fromNode.location, graph.projectRoot, graph.monorepo)) {
+        return true;
+    }
+    if (final.type !== 'registry')
+        return false;
+    const [idType, idRegistry] = splitDepID(n.id);
+    if (idType !== 'registry')
+        return false;
+    const expected = getTuple(spec, {
+        name: n.name,
+        version: n.version,
+    });
+    if (idRegistry !== expected[1])
+        return false;
+    // the package the final spec resolves, never the edge name: an alias
+    // (`foo@npm:bar@^1`, `semver@jsr:@std/semver@^1`) points the same edge
+    // at a different package, and `final.name` already carries the jsr
+    // registry form of the name
+    if (n.name !== final.name)
+        return false;
+    if (!final.range)
+        return true;
+    /* c8 ignore next */
+    if (!n.version)
+        return false;
+    const version = parseVersion(n.version);
+    return !!version && final.range.test(version);
+};
+/**
+ * The lockfile target captured for `fromNode → name` before resetEdges().
+ * A peer-fork rebuild gives fromNode a provisional `peer.N` id that
+ * misses the canonical id key, so retry with the base id key, recorded
+ * only when unambiguous across peer copies.
+ */
+const findLockedNode = (graph, fromNode, name) => {
+    const locked = graph.lockedResolutions;
+    if (!locked)
+        return;
+    let id = locked.get(`${fromNode.id}\0${name}`);
+    if (id === undefined) {
+        const baseFrom = baseDepID(fromNode.id);
+        if (baseFrom !== fromNode.id) {
+            id = locked.get(`${baseFrom}\0${name}`);
+        }
+    }
+    return id ? graph.nodes.get(id) : undefined;
+};
 /**
  * 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 findCompatibleResolution = (spec, fromNode, graph, peerContext, candidate, pending) => {
     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);
-    }
+    // the candidate was picked in the pass before the hydrations
+    let existingNode = candidate;
     let peerCompatResult = existingNode ?
-        checkPeerEdgesCompatible(existingNode, fromNode, peerContext, graph)
+        checkPeerEdgesCompatible(existingNode, fromNode, peerContext, graph, pending)
         : { 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)
+            for (const alt of candidates) {
+                if (alt === existingNode)
                     continue;
-                if (candidate.detached)
+                if (alt.detached)
                     continue;
-                if (!satisfiesFinal(candidate))
+                if (!satisfies(alt.id, final, fromNode.location, graph.projectRoot, graph.monorepo)) {
                     continue;
-                const compat = checkPeerEdgesCompatible(candidate, fromNode, peerContext, graph);
+                }
+                const compat = checkPeerEdgesCompatible(alt, fromNode, peerContext, graph, pending);
                 if (compat.compatible) {
-                    existingNode = candidate;
+                    existingNode = alt;
                     peerCompatResult = compat;
                     break;
                 }
@@ -105,6 +137,55 @@ const findCompatibleResolution = (spec, fromNode, graph, peerContext, queryModif
     }
     return { existingNode, peerCompatResult };
 };
+/**
+ * A detached lockfile node without a manifest still knows its exact
+ * version through its DepID. Rebuild the spec that produced it so the
+ * manifest fetch pins the locked version instead of re-resolving the
+ * range to the newest satisfying release. Only registry nodes carry a
+ * version; anything else keeps the range fetch.
+ */
+const lockedVersionFetch = (node, spec, options) => {
+    if (spec.final.type !== 'registry' || !node.version)
+        return;
+    // hydrate() reproduces alias / named / URL / jsr forms from the DepID
+    // but memoizes per (name, id) ignoring options, so re-parse its
+    // bareSpec with the current options
+    const bare = hydrate(node.id, spec.name, options).bareSpec;
+    const exact = Spec.parse(spec.name, bare, options);
+    // lockedFits only compares the DepID registry name segment; never
+    // fetch a locked version from a source other than the one the edge
+    // resolves to right now
+    if (exact.final.registry !== spec.final.registry)
+        return;
+    return { spec: exact, version: node.version };
+};
+/**
+ * A rebuild without node_modules loads lockfile nodes with no manifest.
+ * Fetch the locked version up front and hydrate the node so the reuse
+ * and peer compatibility decisions see exactly what the hidden-lockfile
+ * path sees; on any miss the node stays bare and the range fetch runs as
+ * before. Hydrations are shared across the parallel fetches of one
+ * appendNodes run so each node is fetched once.
+ */
+const hydrateLockedNode = (node, spec, graph, packageInfo, options, from, hydrations) => {
+    const seen = hydrations.get(node.id);
+    if (seen)
+        return seen;
+    const locked = lockedVersionFetch(node, spec, options);
+    if (!locked)
+        return;
+    const hydration = packageInfo
+        .manifest(locked.spec, { from })
+        .then(manifest => manifest, () => undefined)
+        .then(manifest => {
+        if (manifest?.version !== locked.version)
+            return;
+        node.manifest = normalizeManifest(manifest, String(locked.spec));
+        graph.manifests.set(node.id, node.manifest);
+    });
+    hydrations.set(node.id, hydration);
+    return hydration;
+};
 /**
  * Fetch manifests for dependencies and create placement tasks.
  *
@@ -121,15 +202,20 @@ const findCompatibleResolution = (spec, fromNode, graph, peerContext, queryModif
  * **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) => {
+const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry, options, hydrations, peerContext, modifierRefs, depth = 0, explicit) => {
     const fetchTasks = [];
     const placementTasks = [];
     const reuseTasks = [];
     const forkRequests = [];
+    // resolve the spec each dep is placed with before any lookup
+    const entries = [];
     for (const { spec: originalSpec, type } of deps) {
         let spec = originalSpec;
         const fileTypeInfo = getFileTypeInfo(spec, fromNode, scurry);
         const activeModifier = modifierRefs?.get(spec.name);
+        const isExplicit = !!explicit
+            ?.get(fromNode.id)
+            ?.has(addKey(originalSpec));
         // 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;
@@ -145,18 +231,75 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
                 continue;
             }
         }
+        entries.push({
+            spec,
+            type,
+            fileTypeInfo,
+            activeModifier,
+            queryModifier,
+            isExplicit,
+            // read after the modifier swap, so an --override that replaces the
+            // tag with a range keeps today's reuse
+            explicitTag: isExplicit && !!spec.final.distTag,
+        });
+    }
+    // everything this parent places at this level, by name: the provision
+    // source for optional peers of reuse candidates, explicit adds included
+    const pendingDeps = new Map();
+    for (const e of entries)
+        pendingDeps.set(e.spec.name, e);
+    // pick the reuse candidate once, here, so the placement loop below
+    // does not repeat the lookup, and hydrate it when it is a bare
+    // detached copy from a lockfile loaded without node_modules
+    const from = scurry.resolve(fromNode.location);
+    const pending = [];
+    for (const e of entries) {
+        // prefer the existing edge target when it still satisfies: lockfile
+        // resolutions are preserved rather than re-picked. a rebuild reset
+        // every edge, so this only fires when there was no reset, where no
+        // node is detached and there is nothing to hydrate either
+        const existing = fromNode.edgesOut.get(e.spec.name)?.to;
+        if (existing &&
+            !existing.detached &&
+            satisfies(existing.id, e.spec.final, fromNode.location, graph.projectRoot, graph.monorepo)) {
+            e.candidate = existing;
+            continue;
+        }
+        const locked = findLockedNode(graph, fromNode, e.spec.name);
+        e.candidate =
+            locked && lockedFits(locked, e.spec, fromNode, graph) ? locked
+                : graph.findResolution(e.spec, fromNode, e.queryModifier);
+        // the tag is fetched below anyway, the locked version is dead weight
+        if (e.explicitTag)
+            continue;
+        if (e.candidate?.detached && !e.candidate.manifest) {
+            const hydration = hydrateLockedNode(e.candidate, e.spec, graph, packageInfo, options, from, hydrations);
+            if (hydration)
+                pending.push(hydration);
+        }
+    }
+    await Promise.all(pending);
+    for (const { spec, type, fileTypeInfo, activeModifier, queryModifier, isExplicit, explicitTag, candidate, } of entries) {
         const peer = type === 'peer' || type === 'peerOptional';
         // NODE REUSE LOGIC with peer compatibility
-        const { existingNode, peerCompatResult } = findCompatibleResolution(spec, fromNode, graph, peerContext, queryModifier, peer);
+        const resolved = findCompatibleResolution(spec, fromNode, graph, peerContext, candidate, pendingDeps);
+        // a dist-tag satisfies any node of that name, so reuse is what
+        // installs an arbitrary version for an explicit `pkg@tag` request.
+        // drop the candidate and fetch the tag instead; a registry spec
+        // naming a workspace still links that workspace.
+        const dropForTag = explicitTag &&
+            !!resolved.existingNode &&
+            !resolved.existingNode.importer;
+        const existingNode = dropForTag ? undefined : resolved.existingNode;
+        const peerCompatResult = dropForTag ? { compatible: true } : resolved.peerCompatResult;
         // 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
+        // Locked detached nodes still go through placePackage so
+        // their child edges are rebuilt after resetEdges().
         const validExistingNode = existingNode &&
             !existingNode.detached &&
             // Regular deps can always reuse.
@@ -194,21 +337,28 @@ const fetchManifestsForDeps = async (packageInfo, graph, fromNode, deps, scurry,
         // Start manifest fetch immediately for parallel processing
         const manifestPromise = 
         // 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.manifest ?
+        // part of a graph (either lockfile or actual), or was hydrated with
+        // its locked version above, and it has valid manifest data so we
+        // shortcut the package info manifest fetch here
+        // `keepVersion` marks a fork that only differs by an optional peer
+        // link, so the copy keeps the version it forked from instead of
+        // re-resolving the range to the newest satisfying release
+        (existingNode?.manifest &&
+            (existingNode.detached || peerCompatResult.keepVersion)) ?
             Promise.resolve(existingNode.manifest)
             // this is the entry point to fetch calls to retrieve manifests
             // from the build ideal graph point of view
             : packageInfo
-                .manifest(spec, { from: scurry.resolve(fromNode.location) })
+                .manifest(spec, { from })
                 .then(manifest => manifest)
                 .catch((er) => {
                 // optional deps ignored if inaccessible, but a dep that tried
                 // to escape the project is never silently dropped
                 if (isPathSecurityError(er))
                     throw er;
-                if (edgeOptional || fromNode.optional) {
+                // an explicit request has no version to save if it never
+                // resolved, so it fails the install even when optional
+                if (!isExplicit && (edgeOptional || fromNode.optional)) {
                     return undefined;
                 }
                 throw er;
@@ -324,7 +474,14 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
             !node.isOptional() &&
             // this fixes an issue with installing `file:pathname` specs
             /* c8 ignore next */ !fileTypeInfo?.isDirectory &&
-            !node.importer;
+            !node.importer &&
+            // provisional peer suffixes are rewritten by canonicalizePeerIds,
+            // which moves the store dir into place. Skip when a dir for this
+            // package version already exists: the rewrite most likely lands
+            // back on it, and re-extracting would be pure waste.
+            (!node.peerSetHash ||
+                !!fileTypeInfo ||
+                !hasActualBase(actual, node.id));
         // extract the node if it meets the criteria for early extraction
         if (eligibleForExtraction) {
             /* c8 ignore start */
@@ -432,6 +589,12 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
                 }
             }
         }
+        // a name declared both as a regular dependency (manifest or
+        // transient) and as a peer is the package's own dependency: placing
+        // it once, as the regular type, keeps the edge type independent of
+        // when the peer would have resolved
+        for (const dep of nextDeps)
+            nextPeerDeps.delete(dep.spec.name);
         // finish peer placement for this node, resolving satisfied peers
         // to seen nodes from the peer context and adding unsatisfied peers
         // to `nextDeps` so they get processed along regular dependencies
@@ -465,12 +628,15 @@ const processPlacementTasks = async (graph, options, placementTasks, add, modifi
  * **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) => {
+export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, options, seen, add, modifiers, modifierRefs, extractPromises, actual, seenExtracted, remover, transientAdd, transientRemove, explicit) => {
     // Cycle detection: skip if already processed
     /* c8 ignore next */
     if (seen.has(fromNode.id))
         return;
     seen.add(fromNode.id);
+    // locked lockfile nodes hydrated with their exact manifest, at most
+    // once per node across the parallel fetches
+    const hydrations = new Map();
     // 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.
@@ -516,7 +682,7 @@ export const appendNodes = async (packageInfo, graph, fromNode, deps, scurry, op
             // 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);
+            nodeDeps.sort((a, b) => a.spec.name.localeCompare(b.spec.name, 'en')), scurry, options, hydrations, peerContext, nodeModifierRefs, depth, explicit);
             return {
                 entry: {
                     node,

package/dist/ideal/build-ideal-from-starting-graph.js

@@ -1,4 +1,6 @@
 import { getImporterSpecs } from "./get-importer-specs.js";
+import { canonicalizePeerIds, hasProvisionalPeerIds, } from "./canonicalize-peer-ids.js";
+import { movePeerStoreDirs } from "./move-peer-store-dirs.js";
 import { refreshIdealGraph } from "./refresh-ideal-graph.js";
 import { resolveSaveType } from "../resolve-save-type.js";
 /**
@@ -9,11 +11,21 @@ import { resolveSaveType } from "../resolve-save-type.js";
  * listed in the `add` and `remove` properties.
  */
 export const buildIdealFromStartingGraph = async (options) => {
+    // a graph loaded from a lockfile written by this code is canonical by
+    // construction; only a structural write during this build, or
+    // provisional ids left by an older lockfile, can change that
+    const mutationsBefore = options.graph.mutations;
     // Gets a map of dependencies that are keyed to its importer node ids,
     // merging values already found in the graph with user specified values.
     // Any dependencies that are already satisfied in the starting `graph`
     // are going to be pruned from the resulting object.
     const importerSpecs = getImporterSpecs(options);
+    // snapshot what the user actually asked for before the merge below
+    // folds manifest-derived deltas into `options.add`
+    const explicit = new Map();
+    for (const [id, deps] of options.add) {
+        explicit.set(id, new Set(deps.keys()));
+    }
     // merge modifiedDependencies flags
     options.add.modifiedDependencies =
         options.add.modifiedDependencies ||
@@ -56,14 +68,30 @@ export const buildIdealFromStartingGraph = async (options) => {
             options.remove.get(nodeId)?.add(depName);
         }
     }
+    // an importer edge whose lockfile spec or type no longer matches
+    // package.json while its target still satisfies it: rewrite both so
+    // the rebuild reads the manifest values and the lockfile is saved
+    // carrying them
+    for (const [edge, dep] of importerSpecs.staleSpecs) {
+        edge.spec = dep.spec;
+        edge.type = resolveSaveType(edge.from, edge.name, dep.type);
+    }
+    if (importerSpecs.staleSpecs.size) {
+        options.graph.lockfileStale = true;
+    }
     // refreshs the current graph adding the nodes marked for addition
     // and removing the ones marked for removal, while also recalculating
     // peer dependencies and default locations
     await refreshIdealGraph({
         ...options,
+        explicit,
         transientAdd: importerSpecs.transientAdd,
         transientRemove: importerSpecs.transientRemove,
     });
     options.graph.gc();
+    if (options.graph.mutations !== mutationsBefore ||
+        hasProvisionalPeerIds(options.graph)) {
+        await movePeerStoreDirs(canonicalizePeerIds(options.graph), options);
+    }
     return options.graph;
 };

package/dist/ideal/canonicalize-peer-ids.d.ts

@@ -0,0 +1,44 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { Graph } from '../graph.ts';
+import type { Node } from '../node.ts';
+export type CanonicalizePeerIdsOptions = {
+    digest?: (input: string, length: number) => string;
+};
+export type PeerStoreMove = {
+    node: Node;
+    from: DepID;
+    /** absent = merged-away copy, discard its dir */
+    to?: DepID;
+};
+/**
+ * Any change to this digest, to `serializeNodeEnv`, to `unitEntry` or to
+ * the suffix format changes every peer id in the lockfile, and the ideal
+ * builder no longer re-hashes a graph it did not otherwise touch. Bump
+ * `LOCKFILE_VERSION` alongside it so old lockfiles hard-fail instead of
+ * lingering with stale ids.
+ */
+export declare const peerEnvDigest: (input: string, length?: number) => string;
+/**
+ * `peer.<ordinal>` as minted by retrievePeerContextHash() during a
+ * rebuild, or written by lockfiles from before the hash format.
+ * Canonical suffixes are 16 or 32 hex chars, optionally followed by
+ * `.<role>` or `.x`; an all-digit hash is possible, hence the length
+ * bound rather than a plain `\d+`.
+ */
+export declare const isProvisionalPeerSuffix: (suffix: string) => boolean;
+/**
+ * True when any node still carries a provisional id, so the graph needs
+ * a canonicalization pass even if this build did not write to it.
+ */
+export declare const hasProvisionalPeerIds: (graph: Graph) => boolean;
+export declare const byteCompare: (a: string, b: string) => number;
+export declare const isPeerScoped: (node: Node, graph: Graph) => boolean;
+export declare const serializeNodeEnv: (node: Node, opts?: {
+    resolvedIds?: Map<Node, DepID>;
+    intraSccIndex?: Map<Node, number>;
+}) => string;
+/**
+ * Replace provisional / legacy `peer.<N>` DepID suffixes with a content
+ * hash of each node's resolved out-edge set. Called after `graph.gc()`.
+ */
+export declare const canonicalizePeerIds: (graph: Graph, options?: CanonicalizePeerIdsOptions) => PeerStoreMove[];