@vltpkg/graph 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/graph.d.ts

@@ -0,0 +1,153 @@
+import type { DepID } from '@vltpkg/dep-id';
+import { Spec } from '@vltpkg/spec';
+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 { Edge } from './edge.ts';
+import { Node } from './node.ts';
+import type { PeerContext } from './ideal/types.ts';
+declare const kCustomInspect: unique symbol;
+export type ManifestInventory = Map<DepID, NormalizedManifest>;
+export type GraphOptions = SpecOptions & {
+    /**
+     * The main importer manifest info.
+     */
+    mainManifest: NormalizedManifest;
+    /**
+     * An inventory of seen manifests.
+     */
+    manifests?: ManifestInventory;
+    /**
+     * A {@link Monorepo} object, for managing workspaces
+     */
+    monorepo?: Monorepo;
+    /**
+     * Root of the project this graph represents
+     */
+    projectRoot: string;
+};
+export declare class Graph implements GraphLike {
+    #private;
+    get [Symbol.toStringTag](): string;
+    /**
+     * A {@link Monorepo} instance, used for managing workspaces.
+     */
+    monorepo?: Monorepo;
+    /**
+     * An inventory with all manifests related to an install.
+     */
+    manifests: ManifestInventory;
+    /**
+     * A set of all edges in this graph.
+     */
+    edges: Set<Edge>;
+    /**
+     * Map registered dep ids to the node that represent them in the graph.
+     */
+    nodes: Map<DepID, Node>;
+    /**
+     * Map of nodes by their name
+     */
+    nodesByName: Map<string, Set<Node>>;
+    /**
+     * Cached resolutions for spec lookups
+     */
+    resolutions: Map<string, Node>;
+    /**
+     * Reverse map of resolutions
+     */
+    resolutionsReverse: Map<Node, Set<string>>;
+    /**
+     * A set of importer nodes in this graph.
+     */
+    importers: Set<Node>;
+    /**
+     * The {@link Node} that represents the project root `package.json`.
+     */
+    mainImporter: Node;
+    /**
+     * A set of extraneous dependencies found when building the graph.
+     */
+    extraneousDependencies: Set<Edge>;
+    /**
+     * The root of the project this graph represents
+     */
+    projectRoot: string;
+    /**
+     * The peer context sets used to resolve peer dependencies within this graph.
+     */
+    peerContexts: PeerContext[];
+    /**
+     * Cache of forked peer contexts so identical fork operations can reuse
+     * previously created contexts instead of duplicating them.
+     *
+     * Key format is internal and constructed in `ideal/peers.ts`.
+     */
+    peerContextForkCache: Map<string, PeerContext>;
+    /**
+     * Tracks the current peer context index.
+     */
+    currentPeerContextIndex: number;
+    constructor(options: GraphOptions);
+    /**
+     * Get the next peer context index.
+     */
+    nextPeerContextIndex(): number;
+    /**
+     * 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
+     * optional node fails to resolve/install.
+     */
+    gc(): Map<DepID, Node>;
+    /**
+     * 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: DependencySaveType, spec: Spec, from: NodeLike, to?: NodeLike): Edge;
+    /**
+     * Find an existing node to satisfy a dependency
+     */
+    findResolution(spec: Spec, fromNode: Node, extra?: string): Node | undefined;
+    /**
+     * Create a new node in the graph.
+     */
+    addNode(id?: DepID, manifest?: NormalizedManifest, spec?: Spec, name?: string, version?: string): Node;
+    /**
+     * Place a new package into the graph representation, creating the new
+     * edges and possibly new nodes that are to be expected when traversing
+     * the graph in a top-down direction, e.g: from importers to leafs.
+     *
+     * For different uses that are not a direct top-down traversal of the graph
+     * consider using `addNode()` and `addEdge()` instead.
+     */
+    placePackage(fromNode: Node, depType: DependencySaveType, spec: Spec, manifest?: NormalizedManifest, id?: DepID, extra?: string): Node | undefined;
+    /**
+     * Removes a node and its relevant edges from the graph.
+     *
+     * Use the `keepEdges` option to keep the edges that were pointing to
+     * this node and only removes their `to` property value.
+     *
+     * If a replacement is provided, then any edges that were previously
+     * pointing to the removed node will be directed to the replacement,
+     * if it is valid to do so.
+     */
+    removeNode(node: Node, replacement?: Node, keepEdges?: boolean): void;
+    /**
+     * Removes the resolved node of a given edge.
+     */
+    removeEdgeResolution(edge: Edge, extra?: string): void;
+    /**
+     * Remove all edges from the graph while preserving nodes and resolution caches.
+     * This allows the graph to be reconstructed efficiently using the existing nodes.
+     */
+    resetEdges(): void;
+    toJSON(): import("./index.ts").LockfileData;
+    [kCustomInspect](_: number, options: InspectOptions): string;
+}
+export {};

package/dist/graph.js

@@ -0,0 +1,444 @@
+import { getId, joinDepIDTuple, splitExtra } from '@vltpkg/dep-id';
+import { error } from '@vltpkg/error-cause';
+import { satisfies } from '@vltpkg/satisfies';
+import { 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 { resolveSaveType } from "./resolve-save-type.js";
+const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
+const cacheKeySeparator = '│';
+// this is always the same, but we don't hard code it as a string,
+// in case the DepID module needs to change its delimiter again ever.
+const mainDepID = joinDepIDTuple(['file', '.']);
+const getMap = (m) => m ?? new Map();
+/**
+ * Get a cache key for a resolution based on the
+ * spec, location and query modifier.
+ */
+const getResolutionCacheKey = (spec, location, extra) => {
+    const f = spec.final;
+    // if it's a file: dep, then the fromNode location matters
+    const fromPrefix = f.type === 'file' ? location + ' : ' : '';
+    // the unique key should also precise what is the type of the spec,
+    // and in the case of a registry, what registry it is from.
+    const typePrecisionKey = f.registry ?
+        `${cacheKeySeparator}registry` +
+            `${cacheKeySeparator}${f.registry}`
+        : f.gitRemote ?
+            `${cacheKeySeparator}git` + `${cacheKeySeparator}${f.gitRemote}`
+            : `${cacheKeySeparator}${f.type}`;
+    const modifierSuffix = `${cacheKeySeparator}${extra}`;
+    return fromPrefix + String(f) + typePrecisionKey + modifierSuffix;
+};
+export class Graph {
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Graph';
+    }
+    #options;
+    #nodeOptions;
+    /**
+     * A {@link Monorepo} instance, used for managing workspaces.
+     */
+    monorepo;
+    /**
+     * An inventory with all manifests related to an install.
+     */
+    manifests;
+    /**
+     * A set of all edges in this graph.
+     */
+    edges = new Set();
+    /**
+     * Map registered dep ids to the node that represent them in the graph.
+     */
+    nodes = new Map();
+    /**
+     * Map of nodes by their name
+     */
+    nodesByName = new Map();
+    /**
+     * Cached resolutions for spec lookups
+     */
+    resolutions = new Map();
+    /**
+     * Reverse map of resolutions
+     */
+    resolutionsReverse = new Map();
+    /**
+     * A set of importer nodes in this graph.
+     */
+    importers = new Set();
+    /**
+     * The {@link Node} that represents the project root `package.json`.
+     */
+    mainImporter;
+    /**
+     * A set of extraneous dependencies found when building the graph.
+     */
+    extraneousDependencies = new Set();
+    /**
+     * The root of the project this graph represents
+     */
+    projectRoot;
+    /**
+     * The peer context sets used to resolve peer dependencies within this graph.
+     */
+    peerContexts;
+    /**
+     * Cache of forked peer contexts so identical fork operations can reuse
+     * previously created contexts instead of duplicating them.
+     *
+     * Key format is internal and constructed in `ideal/peers.ts`.
+     */
+    peerContextForkCache = new Map();
+    /**
+     * Tracks the current peer context index.
+     */
+    currentPeerContextIndex = 0;
+    constructor(options) {
+        const { mainManifest, monorepo } = options;
+        this.#options = options;
+        // hydrate spec options to their full contents, including defaults
+        const specOptions = getOptions({
+            registry: options.registry,
+            registries: options.registries,
+            'git-hosts': options['git-hosts'],
+            'git-host-archives': options['git-host-archives'],
+            'scope-registries': options['scope-registries'],
+            'jsr-registries': options['jsr-registries'],
+            catalog: options.catalog,
+            catalogs: options.catalogs,
+        });
+        this.manifests = getMap(options.manifests);
+        this.projectRoot = options.projectRoot;
+        this.#nodeOptions = {
+            ...this.#options,
+            ...specOptions,
+            graph: this,
+        };
+        // add the project root node
+        const mainImporterLocation = '.';
+        const mainImporterSpec = Spec.parse(mainManifest.name || '(root)', mainImporterLocation);
+        const mainImporter = this.addNode(mainDepID, mainManifest, mainImporterSpec);
+        mainImporter.setImporterLocation(mainImporterLocation);
+        mainImporter.mainImporter = true;
+        this.mainImporter = mainImporter;
+        this.mainImporter.workspaces = new Map();
+        this.importers.add(mainImporter);
+        this.manifests.set(mainImporter.id, mainManifest);
+        // uses the monorepo instance in order to retrieve info on
+        // workspaces and create importer nodes for each of them
+        this.monorepo = monorepo;
+        if (this.monorepo) {
+            for (const ws of this.monorepo) {
+                const wsNode = this.addNode(ws.id, ws.manifest, undefined, ws.name);
+                wsNode.setImporterLocation(`./${ws.path}`);
+                if (wsNode.manifest) {
+                    this.manifests.set(wsNode.id, wsNode.manifest);
+                    // set bins for workspace nodes so they can be linked
+                    // when another importer depends on this workspace
+                    /* c8 ignore next 3 - tested by integration tests */
+                    if (wsNode.manifest.bin) {
+                        wsNode.bins = wsNode.manifest.bin;
+                    }
+                }
+                this.importers.add(wsNode);
+                // creates a virtual edge to connect the workspaces to the root node
+                const edge = new Edge('prod', Spec.parse(wsNode.name, 'workspace:*', this.#options), this.mainImporter, wsNode);
+                this.mainImporter.workspaces.set(wsNode.name, edge);
+            }
+        }
+        // initializes the peer context set collection
+        const initialPeerContext = new Map();
+        initialPeerContext.index = this.currentPeerContextIndex;
+        this.peerContexts = [initialPeerContext];
+    }
+    /**
+     * Get the next peer context index.
+     */
+    nextPeerContextIndex() {
+        return ++this.currentPeerContextIndex;
+    }
+    /**
+     * 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
+     * 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()) {
+                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);
+            }
+        }
+        for (const node of nodes.values()) {
+            this.removeNode(node);
+        }
+        return 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) {
+        // fix any nameless spec
+        if (spec.name === '(unknown)') {
+            if (to) {
+                spec.name = to.name /* c8 ignore next */ || '(unknown)';
+                spec.spec = `${to.name}@${spec.bareSpec}`;
+            }
+            else {
+                throw error('Impossible to place a missing, nameless dependency', { spec });
+            }
+        }
+        const existing = from.edgesOut.get(spec.name);
+        if (existing) {
+            const edge = existing;
+            if (edge.type === type &&
+                edge.spec.bareSpec === spec.bareSpec) {
+                if (to && to !== edge.to) {
+                    // removes this edge from its destination edgesIn ref
+                    edge.to?.edgesIn.delete(edge);
+                    // now swap the destination to the new one
+                    edge.to = to;
+                    edge.to.edgesIn.add(edge);
+                }
+                return edge;
+            }
+            this.edges.delete(edge);
+        }
+        const f = from;
+        const edgeOut = f.addEdgesTo(resolveSaveType(from, spec.name, type), spec, to);
+        this.edges.add(edgeOut);
+        return edgeOut;
+    }
+    /**
+     * Find an existing node to satisfy a dependency
+     */
+    findResolution(spec, fromNode, extra = '') {
+        const f = spec.final;
+        const sf = getResolutionCacheKey(f, fromNode.location, extra);
+        const cached = this.resolutions.get(sf);
+        if (cached)
+            return cached;
+        const nbn = this.nodesByName.get(f.name);
+        if (!nbn)
+            return 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;
+            }
+        }
+    }
+    /**
+     * Create a new node in the graph.
+     */
+    addNode(id, manifest, spec, name, version) {
+        const node = new Node(this.#nodeOptions, id, manifest, spec, name, version);
+        this.nodes.set(node.id, node);
+        const nbn = this.nodesByName.get(node.name) ?? new Set();
+        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)));
+        this.nodesByName.set(node.name, newByNameSet);
+        if (manifest) {
+            this.manifests.set(node.id, manifest);
+        }
+        return node;
+    }
+    /**
+     * Place a new package into the graph representation, creating the new
+     * edges and possibly new nodes that are to be expected when traversing
+     * the graph in a top-down direction, e.g: from importers to leafs.
+     *
+     * For different uses that are not a direct top-down traversal of the graph
+     * consider using `addNode()` and `addEdge()` instead.
+     */
+    placePackage(fromNode, depType, spec, manifest, id, extra) {
+        // if no manifest is available, then create an edge that has no
+        // reference to any other node, representing a missing dependency
+        if (!manifest && !id) {
+            this.addEdge(depType, spec, fromNode);
+            return;
+        }
+        // flags set on the node we're about to create or find.
+        const flags = {
+            dev: fromNode.dev || depType === 'dev',
+            optional: fromNode.optional ||
+                depType === 'optional' ||
+                depType === 'peerOptional',
+        };
+        const depId = id || (manifest && getId(spec, manifest, extra));
+        /* c8 ignore start - should not be possible */
+        if (!depId) {
+            throw error('Could not find dep id when placing package', {
+                spec,
+                manifest,
+            });
+        }
+        /* c8 ignore stop */
+        // if a node for this package is already represented by a node
+        // in the graph, then just creates a new edge to that node
+        const toFoundNode = this.nodes.get(depId);
+        if (toFoundNode) {
+            this.addEdge(depType, spec, fromNode, toFoundNode);
+            // the current only stays dev/optional if this dep lets it remain so
+            // if it's not already, we don't make it dev or optional.
+            toFoundNode.detached = false;
+            toFoundNode.dev &&= flags.dev;
+            toFoundNode.optional &&= flags.optional;
+            return toFoundNode;
+        }
+        // creates a new node and edges to its parent
+        const toNode = this.addNode(depId, manifest, spec);
+        toNode.registry = spec.registry;
+        toNode.dev = flags.dev;
+        toNode.optional = flags.optional;
+        // split extra into modifier and peerSetHash
+        if (extra) {
+            const { modifier, peerSetHash } = splitExtra(extra);
+            toNode.modifier = modifier;
+            toNode.peerSetHash = peerSetHash;
+        }
+        // add extra manifest info if available
+        if (manifest) {
+            const { bin, engines, os, cpu, libc } = manifest;
+            // add platform info if available
+            if (engines || os || cpu || libc) {
+                const platform = {};
+                if (engines)
+                    platform.engines = engines;
+                if (os)
+                    platform.os = os;
+                if (cpu)
+                    platform.cpu = cpu;
+                if (libc)
+                    platform.libc = libc;
+                toNode.platform = platform;
+            }
+            // add bin info if available
+            if (bin) {
+                toNode.bins = bin;
+            }
+        }
+        toNode.maybeSetConfusedManifest(spec, manifest);
+        this.addEdge(depType, spec, fromNode, toNode);
+        // populate resolution cache if applicable
+        const f = getResolutionCacheKey(spec.final, fromNode.location, extra || '');
+        this.resolutions.set(f, toNode);
+        const rrev = this.resolutionsReverse.get(toNode) ?? new Set();
+        rrev.add(f);
+        this.resolutionsReverse.set(toNode, rrev);
+        return toNode;
+    }
+    /**
+     * Removes a node and its relevant edges from the graph.
+     *
+     * Use the `keepEdges` option to keep the edges that were pointing to
+     * this node and only removes their `to` property value.
+     *
+     * If a replacement is provided, then any edges that were previously
+     * pointing to the removed node will be directed to the replacement,
+     * if it is valid to do so.
+     */
+    removeNode(node, replacement, keepEdges) {
+        this.nodes.delete(node.id);
+        const nbn = this.nodesByName.get(node.name);
+        // if it's the last one, just remove the set
+        if (nbn?.size === 1)
+            this.nodesByName.delete(node.name);
+        else
+            nbn?.delete(node);
+        for (const r of this.resolutionsReverse.get(node) ?? new Set()) {
+            this.resolutions.delete(r);
+        }
+        this.resolutionsReverse.delete(node);
+        this.manifests.delete(node.id);
+        for (const edge of node.edgesOut.values()) {
+            this.edges.delete(edge);
+        }
+        for (const edge of node.edgesIn) {
+            if (replacement &&
+                satisfies(replacement.id, edge.spec, edge.from.location, this.projectRoot, this.monorepo)) {
+                edge.to = replacement;
+            }
+            else if (keepEdges) {
+                edge.to = undefined;
+            }
+            else {
+                edge.from.edgesOut.delete(edge.spec.name);
+                this.edges.delete(edge);
+            }
+        }
+    }
+    /**
+     * Removes the resolved node of a given edge.
+     */
+    removeEdgeResolution(edge, extra = '') {
+        const node = edge.to;
+        const resolutionKey = getResolutionCacheKey(edge.spec, edge.from.location, extra);
+        if (node) {
+            edge.to = undefined;
+            this.resolutions.delete(resolutionKey);
+            this.resolutionsReverse.get(node)?.delete(resolutionKey);
+            this.nodesByName.delete(node.name);
+            node.edgesIn.delete(edge);
+            if (node.edgesIn.size === 0) {
+                this.nodes.delete(node.id);
+            }
+        }
+    }
+    /**
+     * Remove all edges from the graph while preserving nodes and resolution caches.
+     * This allows the graph to be reconstructed efficiently using the existing nodes.
+     */
+    resetEdges() {
+        // Clear the global edges set
+        this.edges.clear();
+        // Clear all node edge relationships
+        for (const node of this.nodes.values()) {
+            // 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;
+            // detaches all edges from this node
+            node.edgesOut.clear();
+            node.edgesIn.clear();
+        }
+    }
+    toJSON() {
+        return lockfileData({
+            ...this.#options,
+            graph: this,
+            saveManifests: true,
+        });
+    }
+    [kCustomInspect](_, options) {
+        const data = this.toJSON();
+        return `${this[Symbol.toStringTag]} ${inspect(data, options)}`;
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { PackageInfoClient } from '@vltpkg/package-info';
+import type { SpecOptions } from '@vltpkg/spec';
+import type { PathScurry } from 'path-scurry';
+import type { Dependency } from '../dependencies.ts';
+import type { Graph } from '../graph.ts';
+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';
+/**
+ * Append new nodes in the given `graph` for dependencies specified at `add`
+ * and missing dependencies from the `deps` parameter.
+ *
+ * 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 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>;