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

package/dist/ideal/build.d.ts

@@ -0,0 +1,40 @@
+import type { PackageInfoClient } from '@vltpkg/package-info';
+import type { LoadOptions as LoadActualOptions } from '../actual/load.ts';
+import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '../dependencies.ts';
+import type { Graph } from '../graph.ts';
+import type { RollbackRemove } from '@vltpkg/rollback-remove';
+export type BuildIdealOptions = LoadActualOptions & {
+    /**
+     * An actual graph
+     */
+    actual?: Graph;
+    /**
+     * A `Map` in which keys are {@link DepID} linking to another `Map` in which
+     * keys are the dependency names and values are {@link Dependency}. This
+     * structure represents dependencies that need to be added to the importer
+     * represented by {@link DepID}.
+     */
+    add?: AddImportersDependenciesMap;
+    /**
+     * A `Map` object representing nodes to be removed from the ideal graph.
+     * Each {@link DepID} key represents an importer node and the `Set` of
+     * dependency names to be removed from its dependency list.
+     */
+    remove?: RemoveImportersDependenciesMap;
+    /**
+     * A {@link RollbackRemove} instance to handle extraction rollbacks
+     */
+    remover: RollbackRemove;
+    /**
+     * A {@link PackageInfoClient} instance to read manifest info from.
+     */
+    packageInfo: PackageInfoClient;
+};
+/**
+ * Builds an ideal {@link Graph} representing the dependencies that
+ * should be present in order to fulfill the requirements defined
+ * by the `package.json` and `vlt-lock.json` files using either the
+ * virtual or actual graph as a starting point. Also add / remove any
+ * dependencies listed in the `add` and `remove` properties.
+ */
+export declare const build: (options: BuildIdealOptions) => Promise<Graph>;

package/dist/ideal/build.js

@@ -0,0 +1,84 @@
+import { error } from '@vltpkg/error-cause';
+import { graphStep } from '@vltpkg/output';
+import { load as loadActual } from "../actual/load.js";
+import { load as loadVirtual } from "../lockfile/load.js";
+import { buildIdealFromStartingGraph } from "./build-ideal-from-starting-graph.js";
+import { splitDepID } from '@vltpkg/dep-id';
+const getMap = (m) => m ?? new Map();
+/**
+ * Validates that a file dependency node exists in the graph after
+ * a successful graph build. This helps providing an actionable error
+ * message in case the current working directory is a linked nested
+ * folder that hasn't yet been added as a dependency to an importer
+ * in the project.
+ */
+const validateFileDepNode = (graph, id) => {
+    const [type, path] = splitDepID(id);
+    if (type === 'file' && !graph.nodes.get(id)) {
+        throw error('The current working dir is not a dependency of this project', { path });
+    }
+};
+/**
+ * Builds an ideal {@link Graph} representing the dependencies that
+ * should be present in order to fulfill the requirements defined
+ * by the `package.json` and `vlt-lock.json` files using either the
+ * virtual or actual graph as a starting point. Also add / remove any
+ * dependencies listed in the `add` and `remove` properties.
+ */
+export const build = async (options) => {
+    const done = graphStep('build');
+    // Creates the shared instances that are going to be used
+    // in both the loader methods and the build graph
+    const { packageInfo, packageJson, scurry, monorepo } = options;
+    const mainManifest = options.mainManifest ?? packageJson.read(options.projectRoot);
+    let graph;
+    try {
+        graph = loadVirtual({
+            ...options,
+            mainManifest,
+            monorepo,
+        });
+    }
+    catch (err) {
+        // Check if this is a lockfile version mismatch
+        const cause = err.cause;
+        if (cause?.code === 'ELOCKFILEVERSION') {
+            // If lockfile is from a different vlt version, hard fail
+            if (typeof cause.found === 'number' &&
+                typeof cause.wanted === 'number') {
+                throw err;
+            }
+            // TODO: add warning to CLI layer via @vltpkg/output when available
+        }
+        graph = loadActual({
+            ...options,
+            mainManifest,
+            monorepo,
+        });
+    }
+    const res = await buildIdealFromStartingGraph({
+        ...options,
+        scurry,
+        add: getMap(options.add),
+        graph,
+        packageInfo,
+        remove: getMap(options.remove),
+        actual: options.actual,
+    });
+    done();
+    // when adding or removing a new dependency from a file dep,
+    // validate the receiver node was present in the graph
+    if (options.add) {
+        for (const [addKey, value] of options.add.entries()) {
+            if (value.size)
+                validateFileDepNode(res, addKey);
+        }
+    }
+    if (options.remove) {
+        for (const [removeKey, value] of options.remove.entries()) {
+            if (value.size)
+                validateFileDepNode(res, removeKey);
+        }
+    }
+    return res;
+};

package/dist/ideal/get-importer-specs.d.ts

@@ -0,0 +1,20 @@
+import type { AddImportersDependenciesMap, RemoveImportersDependenciesMap } from '../dependencies.ts';
+import type { BuildIdealAddOptions, BuildIdealFromGraphOptions, BuildIdealRemoveOptions, TransientAddMap, TransientRemoveMap } from './types.ts';
+import type { SpecOptions } from '@vltpkg/spec';
+import type { PackageJson } from '@vltpkg/package-json';
+import type { PathScurry } from 'path-scurry';
+export type GetImporterSpecsOptions = BuildIdealAddOptions & BuildIdealFromGraphOptions & BuildIdealRemoveOptions & SpecOptions & {
+    scurry: PathScurry;
+    packageJson: PackageJson;
+};
+/**
+ * Given a {@link Graph} and a list of {@link Dependency}, merges the
+ * dependencies info found in the graph importers and returns the add & remove
+ * results as a Map in which keys are {@link DepID} of each importer node.
+ */
+export declare const getImporterSpecs: (options: GetImporterSpecsOptions) => {
+    add: AddImportersDependenciesMap;
+    remove: RemoveImportersDependenciesMap;
+    transientAdd: TransientAddMap;
+    transientRemove: TransientRemoveMap;
+};

package/dist/ideal/get-importer-specs.js

@@ -0,0 +1,180 @@
+import { longDependencyTypes } from '@vltpkg/types';
+import { shorten, asDependency } from "../dependencies.js";
+import { removeSatisfiedSpecs } from "./remove-satisfied-specs.js";
+import { Spec } from '@vltpkg/spec';
+const hasDepName = (importer, edge) => {
+    for (const depType of longDependencyTypes) {
+        const listedDeps = importer.manifest?.[depType];
+        if (listedDeps && Object.hasOwn(listedDeps, edge.name))
+            return true;
+    }
+    return false;
+};
+class AddImportersDependenciesMapImpl extends Map {
+    modifiedDependencies = false;
+}
+class RemoveImportersDependenciesMapImpl extends Map {
+    modifiedDependencies = false;
+}
+/**
+ * Given a {@link Graph} and a list of {@link Dependency}, merges the
+ * dependencies info found in the graph importers and returns the add & remove
+ * results as a Map in which keys are {@link DepID} of each importer node.
+ */
+export const getImporterSpecs = (options) => {
+    const { add, graph, remove } = options;
+    const addResult = new AddImportersDependenciesMapImpl();
+    const removeResult = new RemoveImportersDependenciesMapImpl();
+    // traverse the list of importers in the starting graph
+    for (const importer of graph.importers) {
+        // uses a Map keying to the spec.name in order to easily make sure there's
+        // only a single dependency entry for a given dependency for each importer
+        const addDeps = new Map();
+        const removeDeps = new Set();
+        // if an edge from the graph is not listed in the manifest,
+        // add that edge to the list of dependencies to be removed
+        for (const edge of importer.edgesOut.values()) {
+            if (!hasDepName(importer, edge) &&
+                !add.get(importer.id)?.has(edge.name)) {
+                removeDeps.add(edge.name);
+                removeResult.modifiedDependencies = true;
+            }
+        }
+        // if a dependency is listed in the manifest but not in the graph,
+        // add that dependency to the list of dependencies to be added
+        for (const depType of longDependencyTypes) {
+            const deps = Object.entries(importer.manifest?.[depType] ?? {});
+            for (const [depName, depSpec] of deps) {
+                const edge = importer.edgesOut.get(depName);
+                // skip if the edge exists and already uses the same spec
+                if (edge?.to && depSpec === edge.spec.bareSpec)
+                    continue;
+                const dependency = asDependency({
+                    spec: Spec.parse(depName, depSpec, options),
+                    type: shorten(depType, depName, importer.manifest),
+                });
+                addDeps.set(depName, dependency);
+            }
+        }
+        addResult.set(importer.id, addDeps);
+        removeResult.set(importer.id, removeDeps);
+    }
+    // Maps to store dependencies targeting non-importer nodes (e.g., nested folders)
+    // These will be injected when the target node is placed in the graph
+    const transientAdd = new Map();
+    const transientRemove = new Map();
+    // Traverse all nodes in the graph to find file type dependencies that are directories
+    // and populate transientAdd/transientRemove with their manifest dependencies
+    // Only process when scurry and packageJson are available
+    for (const node of graph.nodes.values()) {
+        // Skip importers as they're already handled above and also skip
+        // any non-file type dependencies
+        if (graph.importers.has(node) || !node.id.startsWith('file'))
+            continue;
+        // check if this is a file type dependency that is a directory
+        const nodePath = options.scurry.cwd.resolve(node.location);
+        const stat = nodePath.lstatSync();
+        if (stat?.isDirectory()) {
+            // load the manifest for this directory (throw if it does not exist)
+            const manifest = options.packageJson.read(nodePath.fullpath());
+            // should always set the manifest to the read manifest
+            node.manifest = manifest;
+            // create a map of dependencies from the manifest
+            const addDeps = new Map();
+            // check for edges not in manifest (should be removed)
+            const removeDeps = new Set();
+            for (const edge of node.edgesOut.values()) {
+                if (!hasDepName(node, edge) &&
+                    !add.get(node.id)?.has(edge.name)) {
+                    removeDeps.add(edge.name);
+                }
+            }
+            // iterate over manifest dependencies to add them if
+            // they're missing from the graph
+            for (const depType of longDependencyTypes) {
+                const deps = Object.entries(manifest[depType] ?? {});
+                for (const [depName, depSpec] of deps) {
+                    const edge = node.edgesOut.get(depName);
+                    // skip if the edge exists and already uses the same spec
+                    if (edge?.to && depSpec === edge.spec.bareSpec)
+                        continue;
+                    // add the dependency to the addDeps map
+                    const dependency = asDependency({
+                        spec: Spec.parse(depName, depSpec, options),
+                        type: shorten(depType, depName, manifest),
+                    });
+                    addDeps.set(depName, dependency);
+                }
+            }
+            // store in transientAdd if there are any dependencies
+            if (addDeps.size > 0) {
+                transientAdd.set(node.id, addDeps);
+            }
+            // store in transientRemove if there are any to remove
+            if (removeDeps.size > 0) {
+                transientRemove.set(node.id, removeDeps);
+            }
+        }
+    }
+    // merges any provided specs to add to the current found results
+    for (const [id, addDeps] of add.entries()) {
+        const deps = addResult.get(id);
+        if (!deps) {
+            // Not an importer - only store file-type deps for later injection
+            if (id.startsWith('file')) {
+                transientAdd.set(id, addDeps);
+            }
+            continue;
+        }
+        for (const [name, dep] of addDeps.entries()) {
+            deps.set(name, dep);
+        }
+    }
+    // Merges results from user-provided `remove` option with any remove
+    // results found from comparing the manifest with the loaded graph
+    for (const [key, removeSet] of remove) {
+        const importerRemoveItem = removeResult.get(key);
+        if (importerRemoveItem) {
+            for (const depName of removeSet) {
+                importerRemoveItem.add(depName);
+            }
+        }
+        else if (key.startsWith('file')) {
+            // Not an importer - only store file-type deps in transientRemove
+            const existing = transientRemove.get(key);
+            if (existing) {
+                for (const depName of removeSet) {
+                    existing.add(depName);
+                }
+            }
+            else {
+                transientRemove.set(key, new Set(removeSet));
+            }
+        }
+    }
+    // Removes any references to an importer that no longer has specs
+    for (const [key, removeItem] of removeResult) {
+        if (removeItem.size === 0) {
+            removeResult.delete(key);
+        }
+    }
+    // removes already satisfied dependencies from the dependencies list
+    removeSatisfiedSpecs({
+        add: addResult,
+        graph,
+    });
+    // set the modifiedDependencies flag if any
+    // of the importers have modified dependencies
+    for (const addDeps of addResult.values()) {
+        if (addDeps.size > 0) {
+            addResult.modifiedDependencies = true;
+            break;
+        }
+    }
+    return {
+        add: addResult,
+        remove: removeResult,
+        transientAdd,
+        transientRemove,
+    };
+};

package/dist/ideal/peers.d.ts

@@ -0,0 +1,160 @@
+import { Spec } from '@vltpkg/spec';
+import type { PeerContext, PeerContextEntry, PeerContextEntryInput, ProcessPlacementResult } from './types.ts';
+import type { SpecOptions } from '@vltpkg/spec';
+import type { DependencySaveType, Manifest } from '@vltpkg/types';
+import type { Monorepo } from '@vltpkg/workspaces';
+import type { Dependency } from '../dependencies.ts';
+import type { Graph } from '../graph.ts';
+import type { Node } from '../node.ts';
+/**
+ * Result of checking if an existing node's peer edges are compatible
+ * with a new parent's context. The `forkEntry` property is optional
+ * and will only be present if the node's peer edges are incompatible.
+ */
+type PeerEdgeCompatResult = {
+    compatible: boolean;
+    /** When incompatible, entry to add to forked context (target always present) */
+    forkEntry?: PeerContextEntryInput & {
+        target: Node;
+    };
+};
+/**
+ * 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
+ * peer would resolve differently, meaning the node should NOT be reused.
+ *
+ * This is crucial for avoiding incorrect node reuse that would break peer
+ * dependency contracts. Three sources of conflict are checked:
+ *
+ * 1. **Peer context entries**: The global peer context may have resolved a
+ *    different version of a peer dependency than what the existing node expects.
+ *
+ * 2. **Already-placed siblings**: The parent node may already have an edge to
+ *    a different version of the peer dependency.
+ *
+ * 3. **Not-yet-placed siblings**: The parent's manifest declares a dependency
+ *    on the same package, and there's a graph node that would satisfy it but
+ *    differs from what the existing node expects.
+ */
+export declare const checkPeerEdgesCompatible: (existingNode: Node, fromNode: Node, peerContext: PeerContext, graph: Graph) => PeerEdgeCompatResult;
+/**
+ * Retrieve a unique hash value for a given peer context set.
+ */
+export declare const retrievePeerContextHash: (peerContext: PeerContext | undefined) => string | undefined;
+/**
+ * Checks if a given spec is compatible with the specs already
+ * assigned to a peer context entry.
+ *
+ * Returns true if INCOMPATIBLE, false if compatible.
+ *
+ * Compatibility rules:
+ * - **Registry specs**: Uses semver range intersection. `^18.0.0` and `^18.2.0`
+ *   intersect (compatible), but `^18.0.0` and `^19.0.0` don't (incompatible).
+ * - **Non-registry specs** (git, file, etc.): Requires exact bareSpec match.
+ *   `github:foo/bar#v1` only matches itself.
+ *
+ * This is used to determine when peer context forking is needed - if specs
+ * are incompatible, a new peer context must be created.
+ */
+export declare const incompatibleSpecs: (spec: Spec, entry: PeerContextEntry) => boolean;
+/**
+ * Sort peer context entry inputs for deterministic processing.
+ * Orders: non-peer dependencies first, then peer dependencies, alphabetically by name.
+ */
+export declare const getOrderedPeerContextEntries: (entries: PeerContextEntryInput[]) => PeerContextEntryInput[];
+export declare const checkEntriesToPeerContext: (peerContext: PeerContext, entries: PeerContextEntryInput[]) => boolean;
+/**
+ * Add or update dependencies in a given peer context making sure to check
+ * for compatibility with existing dependencies already resolved by a given
+ * peer context set. Extra info such as a target or dependent nodes is
+ * optional.
+ *
+ * Returns true if forking is needed, false otherwise.
+ */
+export declare const addEntriesToPeerContext: (peerContext: PeerContext, entries: PeerContextEntryInput[], fromNode: Node, monorepo?: Monorepo) => boolean;
+/**
+ * Create and returns a forked copy of a given peer context set.
+ */
+export declare const forkPeerContext: (graph: Graph, peerContext: PeerContext, entries: PeerContextEntryInput[]) => PeerContext;
+/**
+ * Starts the peer dependency placement process
+ * for a given node being processed and placed.
+ */
+export declare const startPeerPlacement: (peerContext: PeerContext, manifest: Manifest, fromNode: Node, options: SpecOptions) => {
+    peerSetHash: string | undefined;
+    queuedEntries: PeerContextEntryInput[];
+};
+/**
+ * Ends the peer dependency placement process, returning the functions that
+ * are going to be used to update the peer context set, forking when needed
+ * and resolving peer dependencies if possible.
+ *
+ * Returns two deferred functions:
+ * - `putEntries()`: Adds entries to peer context; returns fork entries if conflict
+ * - `resolvePeerDeps()`: Resolves peer deps from context/siblings or adds to nextDeps
+ *
+ * These are deferred (not executed immediately) so that all siblings at a level
+ * can be processed before peer context updates, enabling context reuse optimization.
+ */
+export declare const endPeerPlacement: (peerContext: PeerContext, nextDeps: Dependency[], nextPeerDeps: Map<string, Dependency> & {
+    id?: number;
+}, graph: Graph, spec: Spec, fromNode: Node, node: Node, type: DependencySaveType, queuedEntries: PeerContextEntryInput[]) => {
+    /**
+     * Add the new entries to the current peer context set.
+     *
+     * Two sets of entries are checked:
+     * - `prevEntries`: Parent's queued entries + self-reference
+     * - `nextEntries`: This node's deps + peer deps (with node as dependent)
+     *
+     * If either conflicts with the current context, returns ALL entries to be
+     * added to a forked context (prevEntries last for priority).
+     *
+     * Returns `undefined` if no fork needed (entries added directly to context).
+     */
+    putEntries: () => (PeerContextEntryInput | {
+        dependent: Node;
+        spec: import("@vltpkg/spec/browser").Spec;
+        type: DependencySaveType;
+    } | {
+        spec: Spec;
+        target: Node;
+        type: DependencySaveType;
+    })[] | undefined;
+    /**
+     * Try to resolve peer dependencies using already seen target
+     * values from the current peer context set.
+     *
+     * Resolution priority (highest to lowest):
+     * 1. Sibling deps from parent (workspace direct deps take priority)
+     * 2. Peer-edge closure of sibling targets (handles peer cycles)
+     * 3. Global peer context set entries
+     * 4. Add to nextDeps for normal resolution (or create dangling edge for optional)
+     */
+    resolvePeerDeps: () => void;
+};
+/**
+ * Given an array of processed results for the current level dependencies
+ * being placed in the currently building ideal graph, traverse its direct
+ * dependencies and track peer dependencies in their appropriate peer context
+ * sets, forking as needed and resolving peer dependencies using suitable
+ * nodes already present in the graph if possible.
+ *
+ * This is the core peer context management algorithm, executed after each
+ * BFS level. It runs in three phases:
+ *
+ * **Phase 1: Collect fork requirements**
+ * Call `putEntries()` on each child dep to add entries to peer context.
+ * Collect which children need forked contexts (due to conflicts).
+ *
+ * **Phase 2: Fork or reuse contexts**
+ * For children needing forks, try to reuse a sibling's forked context if
+ * compatible. This optimization reduces the number of peer contexts created.
+ *
+ * **Phase 3: Resolve peer deps**
+ * With contexts finalized, call `resolvePeerDeps()` to create edges for
+ * peers that can be satisfied from context/siblings, or add them to nextDeps.
+ *
+ * All operations are sorted by `node.id` for deterministic, reproducible builds.
+ */
+export declare const postPlacementPeerCheck: (graph: Graph, sortedLevelResults: ProcessPlacementResult[]) => void;
+export {};