@vltpkg/graph 1.0.0-rc.9 → 1.0.1

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 {};