@vltpkg/graph 1.0.6 → 1.0.8

package/dist/actual/load.js

@@ -352,6 +352,7 @@ export const load = (options) => {
             });
         }
     }
+    graph.sortNodes();
     done();
     return graph;
 };

package/dist/dependencies.d.ts

@@ -53,10 +53,26 @@ export type RemoveImportersDependenciesMap = Map<DepID, Set<string>> & {
 };
 export declare const isDependency: (o: unknown) => o is Dependency;
 export declare const asDependency: (obj: unknown) => Dependency;
+/**
+ * The key an added dependency is filed under. A nameless spec
+ * (`github:u/r`, `file:../x`, a tarball url) has no name to key by, so
+ * the CLI uses its stringified form; every reader of an `add` map has to
+ * derive the key the same way.
+ */
+export declare const addKey: (spec: Spec) => string;
 /**
  * Get the {@link DependencyTypeShort} from a {@link DependencyTypeLong}.
  */
 export declare const shorten: (typeLong: DependencyTypeLong, name?: string, manifest?: Pick<Manifest, "peerDependenciesMeta"> | null) => DependencyTypeShort;
+/**
+ * Only install devDeps for git dependencies and importers
+ * Everything else always gets installed
+ *
+ * Deliberately stricter than {@link getRawDependencies}, which also keeps
+ * devDeps of `file:` nodes: this is the rule the ideal build places with, so
+ * peer checks use it to match what actually lands in the graph.
+ */
+export declare const shouldInstallDepType: (node: NodeLike, depType: DependencyTypeLong) => boolean;
 export declare const getRawDependencies: (node: NodeLike) => Map<string, RawDependency>;
 /**
  * Retrieves a map of all dependencies, of all types, that can be inferred

package/dist/dependencies.js

@@ -27,6 +27,13 @@ export const asDependency = (obj) => {
     }
     return obj;
 };
+/**
+ * The key an added dependency is filed under. A nameless spec
+ * (`github:u/r`, `file:../x`, a tarball url) has no name to key by, so
+ * the CLI uses its stringified form; every reader of an `add` map has to
+ * derive the key the same way.
+ */
+export const addKey = (spec) => spec.name === '(unknown)' ? spec.spec : spec.name;
 /**
  * Get the {@link DependencyTypeShort} from a {@link DependencyTypeLong}.
  */
@@ -48,6 +55,17 @@ export const shorten = (typeLong, name, manifest) => {
     return 'peer';
 };
 const isStringArray = (a) => Array.isArray(a) && !a.some(b => typeof b !== 'string');
+/**
+ * Only install devDeps for git dependencies and importers
+ * Everything else always gets installed
+ *
+ * Deliberately stricter than {@link getRawDependencies}, which also keeps
+ * devDeps of `file:` nodes: this is the rule the ideal build places with, so
+ * peer checks use it to match what actually lands in the graph.
+ */
+export const shouldInstallDepType = (node, depType) => depType !== 'devDependencies' ||
+    node.importer ||
+    node.id.startsWith('git');
 /*
  * Retrieves a map of all dependencies, of all types, that can be iterated
  * on and consulted when parsing the directory contents of a given node.
@@ -78,6 +96,12 @@ export const getRawDependencies = (node) => {
                 // if it's a bundled dependency, we just ignore it entirely.
                 if (bundled.has(name))
                     continue;
+                // a name already collected from a regular dependency type is the
+                // package's own dependency; the peer entry only constrains it
+                if (depType === 'peerDependencies' &&
+                    dependencies.has(name)) {
+                    continue;
+                }
                 dependencies.set(name, {
                     name,
                     type: depType,

package/dist/fixup-added-names.js

@@ -1,4 +1,5 @@
 import { Spec } from '@vltpkg/spec';
+import { addKey } from "./dependencies.js";
 import { calculateSaveValue } from "./reify/calculate-save-value.js";
 /**
  * When adding new dependencies, it's very common to not have a dependency
@@ -16,10 +17,11 @@ import { calculateSaveValue } from "./reify/calculate-save-value.js";
 export const fixupAddedNames = (add, manifest, options, spec) => {
     // Handle nameless dependencies
     if (add && manifest?.name && spec.name === '(unknown)') {
-        const s = add.get(String(spec));
+        const key = addKey(spec);
+        const s = add.get(key);
         if (s) {
             // removes the previous, placeholder entry key
-            add.delete(String(spec));
+            add.delete(key);
             // replaces spec with a version with the correct name
             spec = Spec.parse(manifest.name, spec.bareSpec, options);
             // updates the add map with the fixed up spec

package/dist/graph.d.ts

@@ -4,6 +4,7 @@ import type { SpecOptions } from '@vltpkg/spec';
 import type { GraphLike, NodeLike, NormalizedManifest, DependencySaveType } from '@vltpkg/types';
 import type { Monorepo } from '@vltpkg/workspaces';
 import type { InspectOptions } from 'node:util';
+import type { OptionsChange } from './lockfile/types.ts';
 import { Edge } from './edge.ts';
 import { Node } from './node.ts';
 import type { PeerContext } from './ideal/types.ts';
@@ -91,10 +92,35 @@ export declare class Graph implements GraphLike {
      * the ideal builder must reset edges and rebuild the graph.
      */
     optionsChanged: boolean;
+    /**
+     * The individual differences behind `optionsChanged`, in the order
+     * they are reported to the user. Empty when nothing changed.
+     */
+    optionsChanges: OptionsChange[];
+    /**
+     * Whether the lockfile on disk no longer matches this graph even
+     * though no node changed, e.g. an importer edge spec was rewritten to
+     * the value saved to `package.json`, or the config options the graph
+     * was built with differ from the ones stored in the lockfile. Reify
+     * saves the lockfiles from its no-diff early return when set.
+     */
+    lockfileStale: boolean;
+    /**
+     * Lockfile edge targets captured immediately before `resetEdges()`.
+     * Used by the ideal builder to reuse locked resolutions across a rebuild.
+     */
+    lockedResolutions?: Map<string, DepID>;
     /**
      * Tracks the current peer context index.
      */
     currentPeerContextIndex: number;
+    /**
+     * Count of structural writes: nodes placed or removed, edges reset,
+     * created or re-pointed. Never reset; callers snapshot it and compare,
+     * so the ideal builder can tell whether a rebuild touched anything the
+     * peer identities depend on.
+     */
+    mutations: number;
     constructor(options: GraphOptions);
     /**
      * Get the next peer context index.
@@ -104,12 +130,23 @@ export declare class Graph implements GraphLike {
      * Delete all nodes and edges that are unreachable from the importers.
      * The collection of deleted nodes is returned.
      *
-     * NOTE: This can be extremely slow for large graphs, and is almost always
-     * unnecessary! Only call when it is known that some unreachable nodes may
-     * have been created, for example when deleting the unneeded subgraph when an
+     * Marking is O(N+E) and always runs, but when nothing is unreachable
+     * and every reachable node is registered under its own id, `nodes` is
+     * left alone — no rebuild, no sort, and an empty map is returned.
+     * Only call when it is known that some unreachable nodes may have been
+     * created, for example when deleting the unneeded subgraph when an
      * optional node fails to resolve/install.
      */
     gc(): Map<DepID, Node>;
+    /**
+     * Rebuild `nodes` so importers come first, then remaining nodes in
+     * DepID order. Matches lockfile save so a built graph and a
+     * save→load round-trip iterate the same way.
+     *
+     * A graph coming from the lockfile loader is already in that order, so
+     * the pass below detects it and keeps the map as-is.
+     */
+    sortNodes(): void;
     /**
      * Create a new edge between two nodes of the graph in case both exist,
      * in case the destination node does not exists, then a dangling edge,
@@ -153,7 +190,7 @@ export declare class Graph implements GraphLike {
      * This allows the graph to be reconstructed efficiently using the existing nodes.
      */
     resetEdges(): void;
-    toJSON(): import("./index.ts").LockfileData;
+    toJSON(): import("./lockfile/types.ts").LockfileData;
     [kCustomInspect](_: number, options: InspectOptions): string;
 }
 export {};

package/dist/graph.js

@@ -1,11 +1,11 @@
-import { getId, joinDepIDTuple, splitExtra } from '@vltpkg/dep-id';
+import { baseDepID, getId, joinDepIDTuple, splitExtra, } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { satisfies } from '@vltpkg/satisfies';
 import { assertPathSafeName, getOptions, Spec } from '@vltpkg/spec';
 import { inspect } from 'node:util';
 import { lockfileData } from "./lockfile/save.js";
 import { Edge } from "./edge.js";
-import { Node } from "./node.js";
+import { copyPackageMetadata, Node } from "./node.js";
 import { resolveSaveType } from "./resolve-save-type.js";
 const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
 const cacheKeySeparator = '│';
@@ -102,10 +102,35 @@ export class Graph {
      * the ideal builder must reset edges and rebuild the graph.
      */
     optionsChanged = false;
+    /**
+     * The individual differences behind `optionsChanged`, in the order
+     * they are reported to the user. Empty when nothing changed.
+     */
+    optionsChanges = [];
+    /**
+     * Whether the lockfile on disk no longer matches this graph even
+     * though no node changed, e.g. an importer edge spec was rewritten to
+     * the value saved to `package.json`, or the config options the graph
+     * was built with differ from the ones stored in the lockfile. Reify
+     * saves the lockfiles from its no-diff early return when set.
+     */
+    lockfileStale = false;
+    /**
+     * Lockfile edge targets captured immediately before `resetEdges()`.
+     * Used by the ideal builder to reuse locked resolutions across a rebuild.
+     */
+    lockedResolutions;
     /**
      * Tracks the current peer context index.
      */
     currentPeerContextIndex = 0;
+    /**
+     * Count of structural writes: nodes placed or removed, edges reset,
+     * created or re-pointed. Never reset; callers snapshot it and compare,
+     * so the ideal builder can tell whether a rebuild touched anything the
+     * peer identities depend on.
+     */
+    mutations = 0;
     constructor(options) {
         const { mainManifest, monorepo } = options;
         this.#options = options;
@@ -174,41 +199,97 @@ export class Graph {
      * Delete all nodes and edges that are unreachable from the importers.
      * The collection of deleted nodes is returned.
      *
-     * NOTE: This can be extremely slow for large graphs, and is almost always
-     * unnecessary! Only call when it is known that some unreachable nodes may
-     * have been created, for example when deleting the unneeded subgraph when an
+     * Marking is O(N+E) and always runs, but when nothing is unreachable
+     * and every reachable node is registered under its own id, `nodes` is
+     * left alone — no rebuild, no sort, and an empty map is returned.
+     * Only call when it is known that some unreachable nodes may have been
+     * created, for example when deleting the unneeded subgraph when an
      * optional node fails to resolve/install.
      */
     gc() {
         const { nodes } = this;
         this.edges.clear();
-        this.nodes = new Map();
         const marked = new Set(this.importers);
-        for (const imp of marked) {
-            // don't delete the importer!
-            nodes.delete(imp.id);
-            this.nodes.set(imp.id, imp);
-            for (const edge of imp.edgesOut.values()) {
+        for (const node of marked) {
+            for (const edge of node.edgesOut.values()) {
                 this.edges.add(edge);
                 const { to } = edge;
-                if (!to || marked.has(to))
-                    continue;
-                marked.add(to);
-                nodes.delete(to.id);
-                this.nodes.set(to.id, to);
+                if (to)
+                    marked.add(to);
             }
         }
+        let intact = marked.size === nodes.size;
+        if (intact) {
+            for (const node of marked) {
+                if (nodes.get(node.id) !== node) {
+                    intact = false;
+                    break;
+                }
+            }
+        }
+        if (intact)
+            return new Map();
+        this.nodes = new Map();
+        for (const node of marked) {
+            // don't delete the reachable ones!
+            nodes.delete(node.id);
+            this.nodes.set(node.id, node);
+        }
         for (const node of nodes.values()) {
             this.removeNode(node);
         }
+        this.sortNodes();
         return nodes;
     }
+    /**
+     * Rebuild `nodes` so importers come first, then remaining nodes in
+     * DepID order. Matches lockfile save so a built graph and a
+     * save→load round-trip iterate the same way.
+     *
+     * A graph coming from the lockfile loader is already in that order, so
+     * the pass below detects it and keeps the map as-is.
+     */
+    sortNodes() {
+        const cmp = (a, b) => a.id.localeCompare(b.id, 'en');
+        const rest = [];
+        const importers = this.importers.values();
+        let seenImporters = 0;
+        let sorted = true;
+        let prev;
+        for (const node of this.nodes.values()) {
+            if (this.importers.has(node)) {
+                // importers must come first, in importer-set order
+                if (rest.length || importers.next().value !== node) {
+                    sorted = false;
+                }
+                seenImporters++;
+                continue;
+            }
+            if (sorted && prev && cmp(prev, node) > 0)
+                sorted = false;
+            prev = node;
+            rest.push(node);
+        }
+        if (sorted && seenImporters === this.importers.size)
+            return;
+        rest.sort(cmp);
+        const nodes = new Map();
+        for (const node of this.importers)
+            nodes.set(node.id, node);
+        for (const node of rest)
+            nodes.set(node.id, node);
+        this.nodes = nodes;
+    }
     /**
      * Create a new edge between two nodes of the graph in case both exist,
      * in case the destination node does not exists, then a dangling edge,
      * pointing to nothing will be created to represent that missing dependency.
      */
     addEdge(type, spec, from, to) {
+        if (to) {
+            const toNode = to;
+            toNode.detached = false;
+        }
         // fix any nameless spec
         if (spec.name === '(unknown)') {
             if (to) {
@@ -227,6 +308,7 @@ export class Graph {
             if (edge.type === type &&
                 edge.spec.bareSpec === spec.bareSpec) {
                 if (to && to !== edge.to) {
+                    this.mutations++;
                     // removes this edge from its destination edgesIn ref
                     edge.to?.edgesIn.delete(edge);
                     // now swap the destination to the new one
@@ -237,6 +319,7 @@ export class Graph {
             }
             this.edges.delete(edge);
         }
+        this.mutations++;
         const f = from;
         const edgeOut = f.addEdgesTo(resolveSaveType(from, spec.name, type), spec, to);
         this.edges.add(edgeOut);
@@ -249,19 +332,31 @@ export class Graph {
         const f = spec.final;
         const sf = getResolutionCacheKey(f, fromNode.location, extra);
         const cached = this.resolutions.get(sf);
-        if (cached)
+        if (cached && !cached.detached)
             return cached;
         const nbn = this.nodesByName.get(f.name);
         if (!nbn)
             return undefined;
+        const sat = (n) => satisfies(n.id, f, fromNode.location, this.projectRoot, this.monorepo);
+        // a live node always wins; a detached one is only a fallback, and is
+        // never cached, placePackage caches it again when it reattaches. a
+        // detached cached entry is what this location resolved to last time,
+        // so it wins over nodesByName (sorted id) order - but the cache is
+        // written at placement, not by satisfies(), so re-check it here.
+        let detached = cached?.detached && sat(cached) ? cached : undefined;
         for (const node of nbn) {
-            if (satisfies(node.id, f, fromNode.location, this.projectRoot, this.monorepo)) {
-                this.resolutions.set(sf, node);
-                // always set by now, because the node was added at some point
-                this.resolutionsReverse.get(node)?.add(sf);
-                return node;
+            if (!sat(node))
+                continue;
+            if (node.detached) {
+                detached ??= node;
+                continue;
             }
+            this.resolutions.set(sf, node);
+            // always set by now, because the node was added at some point
+            this.resolutionsReverse.get(node)?.add(sf);
+            return node;
         }
+        return detached;
     }
     /**
      * Create a new node in the graph.
@@ -273,7 +368,7 @@ export class Graph {
         nbn.add(node);
         // ensure the nodes by name set is always sorted, this will help
         // keeping a deterministic graph resolution when reusing nodes
-        const newByNameSet = new Set([...nbn].sort((a, b) => a.id.localeCompare(b.id)));
+        const newByNameSet = new Set([...nbn].sort((a, b) => a.id.localeCompare(b.id, 'en')));
         this.nodesByName.set(node.name, newByNameSet);
         if (manifest) {
             this.manifests.set(node.id, manifest);
@@ -289,6 +384,7 @@ export class Graph {
      * consider using `addNode()` and `addEdge()` instead.
      */
     placePackage(fromNode, depType, spec, manifest, id, extra) {
+        this.mutations++;
         // if no manifest is available, then create an edge that has no
         // reference to any other node, representing a missing dependency
         if (!manifest && !id) {
@@ -336,10 +432,30 @@ export class Graph {
             return toFoundNode;
         }
         // creates a new node and edges to its parent
+        // Peer-fork rebuilds mint a provisional `peer.N` DepID that does not
+        // match the lockfile's content-hash ID, so exact-ID reuse misses.
+        // Copy integrity/resolved from the same package version (same tarball).
+        let samePackage;
+        const base = baseDepID(depId);
+        const nbn = this.nodesByName.get(manifest?.name ?? spec.name);
+        if (nbn) {
+            for (const n of nbn) {
+                if (baseDepID(n.id) !== base)
+                    continue;
+                if (!n.integrity && !n.resolved)
+                    continue;
+                samePackage = n;
+                if (n.integrity)
+                    break;
+            }
+        }
         const toNode = this.addNode(depId, manifest, spec);
         toNode.registry = spec.registry;
         toNode.dev = flags.dev;
         toNode.optional = flags.optional;
+        if (samePackage)
+            copyPackageMetadata(toNode, samePackage);
+        toNode.integrity ??= manifest?.dist?.integrity;
         // split extra into modifier and peerSetHash
         if (extra) {
             const { modifier, peerSetHash } = splitExtra(extra);
@@ -388,6 +504,7 @@ export class Graph {
      * if it is valid to do so.
      */
     removeNode(node, replacement, keepEdges) {
+        this.mutations++;
         this.nodes.delete(node.id);
         const nbn = this.nodesByName.get(node.name);
         // if it's the last one, just remove the set
@@ -421,6 +538,7 @@ export class Graph {
      * Removes the resolved node of a given edge.
      */
     removeEdgeResolution(edge, extra = '') {
+        this.mutations++;
         const node = edge.to;
         const resolutionKey = getResolutionCacheKey(edge.spec, edge.from.location, extra);
         if (node) {
@@ -439,6 +557,7 @@ export class Graph {
      * This allows the graph to be reconstructed efficiently using the existing nodes.
      */
     resetEdges() {
+        this.mutations++;
         // Clear the global edges set
         this.edges.clear();
         // Clear all node edge relationships
@@ -446,8 +565,9 @@ export class Graph {
             // Mark nodes as detached so ideal rebuild treats them as candidates
             // that must be (re)placed during traversal. Detached nodes with a
             // manifest can skip refetch; detached nodes without a manifest must
-            // fetch from package-info during ideal rebuild.
-            node.detached = true;
+            // fetch from package-info during ideal rebuild. Importers are the
+            // traversal roots and are never re-placed, so they stay attached.
+            node.detached = !node.importer;
             // detaches all edges from this node
             node.edgesOut.clear();
             node.edgesIn.clear();

package/dist/ideal/append-nodes.d.ts

@@ -8,7 +8,7 @@ import type { Node } from '../node.ts';
 import type { GraphModifier, ModifierActiveEntry } from '../modifiers.ts';
 import type { ExtractResult } from '../reify/extract-node.ts';
 import type { RollbackRemove } from '@vltpkg/rollback-remove';
-import type { TransientAddMap, TransientRemoveMap } from './types.ts';
+import type { ExplicitAddMap, TransientAddMap, TransientRemoveMap } from './types.ts';
 /**
  * Append new nodes in the given `graph` for dependencies specified at `add`
  * and missing dependencies from the `deps` parameter.
@@ -28,4 +28,4 @@ import type { TransientAddMap, TransientRemoveMap } from './types.ts';
  * **Early Extraction**: When `actual` graph is provided, nodes are extracted
  * to the vlt store during graph construction (not after), improving performance.
  */
-export declare const appendNodes: (packageInfo: PackageInfoClient, graph: Graph, fromNode: Node, deps: Dependency[], scurry: PathScurry, options: SpecOptions, seen: Set<DepID>, add?: Map<string, Dependency>, modifiers?: GraphModifier, modifierRefs?: Map<string, ModifierActiveEntry>, extractPromises?: Promise<ExtractResult>[], actual?: Graph, seenExtracted?: Set<DepID>, remover?: RollbackRemove, transientAdd?: TransientAddMap, transientRemove?: TransientRemoveMap) => Promise<void>;
+export declare const appendNodes: (packageInfo: PackageInfoClient, graph: Graph, fromNode: Node, deps: Dependency[], scurry: PathScurry, options: SpecOptions, seen: Set<DepID>, add?: Map<string, Dependency>, modifiers?: GraphModifier, modifierRefs?: Map<string, ModifierActiveEntry>, extractPromises?: Promise<ExtractResult>[], actual?: Graph, seenExtracted?: Set<DepID>, remover?: RollbackRemove, transientAdd?: TransientAddMap, transientRemove?: TransientRemoveMap, explicit?: ExplicitAddMap) => Promise<void>;