@vltpkg/graph 1.0.0-rc.14 → 1.0.0-rc.15

package/dist/ideal/peers.d.ts

@@ -13,17 +13,28 @@ import type { Node } from '../node.ts';
  */
 type PeerEdgeCompatResult = {
     compatible: boolean;
-    /** When incompatible, entry to add to forked context */
-    forkEntry?: {
-        spec: Spec;
+    /** When incompatible, entry to add to forked context (target always present) */
+    forkEntry?: PeerContextEntryInput & {
         target: Node;
-        type: DependencySaveType;
     };
 };
 /**
  * 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;
 /**
@@ -34,7 +45,16 @@ export declare const retrievePeerContextHash: (peerContext: PeerContext | undefi
  * Checks if a given spec is compatible with the specs already
  * assigned to a peer context entry.
  *
- * Returns true if compatible, false otherwise.
+ * 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;
 /**
@@ -68,21 +88,47 @@ export declare const startPeerPlacement: (peerContext: PeerContext, manifest: Ma
  * 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: () => {
+    putEntries: () => (PeerContextEntryInput | {
         dependent: Node;
         spec: import("@vltpkg/spec/browser").Spec;
         type: DependencySaveType;
-    }[] | undefined;
+    } | {
+        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;
 };
@@ -92,6 +138,23 @@ export declare const endPeerPlacement: (peerContext: PeerContext, nextDeps: Depe
  * 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 {};

package/dist/ideal/peers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peers.d.ts","sourceRoot":"","sources":["../../src/ideal/peers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAGnC,OAAO,KAAK,EAEV,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;GAIG;AACH,KAAK,oBAAoB,GAAG;IAC1B,UAAU,EAAE,OAAO,CAAA;IACnB,wDAAwD;IACxD,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,IAAI,CAAA;QACV,MAAM,EAAE,IAAI,CAAA;QACZ,IAAI,EAAE,kBAAkB,CAAA;KACzB,CAAA;CACF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,iBACrB,IAAI,YACR,IAAI,eACD,WAAW,SACjB,KAAK,KACX,oBAuIF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,gBACrB,WAAW,GAAG,SAAS,KACnC,MAAM,GAAG,SAKX,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SACtB,IAAI,SACH,gBAAgB,KACtB,OAmBF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,YAC9B,qBAAqB,EAAE,KAC/B,qBAAqB,EAUpB,CAAA;AAQJ,eAAO,MAAM,yBAAyB,gBACvB,WAAW,WACf,qBAAqB,EAAE,KAC/B,OAgBF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,gBACrB,WAAW,WACf,qBAAqB,EAAE,YACtB,IAAI,aACH,QAAQ,KAClB,OAwEF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,UACnB,KAAK,eACC,WAAW,WACf,qBAAqB,EAAE,KAC/B,WAqCF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gBAChB,WAAW,YACd,QAAQ,YACR,IAAI,WACL,WAAW;;;CA4CrB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,gBACd,WAAW,YACd,UAAU,EAAE,gBACR,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,SAChD,KAAK,QACN,IAAI,YACA,IAAI,QACR,IAAI,QACJ,kBAAkB,iBACT,qBAAqB,EAAE;IAEtC;;OAEG;;;;;;IA2CH;;;OAGG;;CAyEH,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,UAC1B,KAAK,sBACQ,sBAAsB,EAAE,SAiE7C,CAAA"}
+{"version":3,"file":"peers.d.ts","sourceRoot":"","sources":["../../src/ideal/peers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAGnC,OAAO,KAAK,EAEV,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,KAAK,EACV,kBAAkB,EAElB,QAAQ,EACT,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;GAIG;AACH,KAAK,oBAAoB,GAAG;IAC1B,UAAU,EAAE,OAAO,CAAA;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,qBAAqB,GAAG;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,CAAA;CACrD,CAAA;AA6ID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,iBACrB,IAAI,YACR,IAAI,eACD,WAAW,SACjB,KAAK,KACX,oBAuHF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,gBACrB,WAAW,GAAG,SAAS,KACnC,MAAM,GAAG,SAKX,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,SACtB,IAAI,SACH,gBAAgB,KACtB,OAkBF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,YAC9B,qBAAqB,EAAE,KAC/B,qBAAqB,EAAsC,CAAA;AAQ9D,eAAO,MAAM,yBAAyB,gBACvB,WAAW,WACf,qBAAqB,EAAE,KAC/B,OAgBF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,gBACrB,WAAW,WACf,qBAAqB,EAAE,YACtB,IAAI,aACH,QAAQ,KAClB,OA6DF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,UACnB,KAAK,eACC,WAAW,WACf,qBAAqB,EAAE,KAC/B,WA4CF,CAAA;AA0DD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gBAChB,WAAW,YACd,QAAQ,YACR,IAAI,WACL,WAAW;;;CA4CrB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,gBACd,WAAW,YACd,UAAU,EAAE,gBACR,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,SAChD,KAAK,QACN,IAAI,YACA,IAAI,QACR,IAAI,QACJ,kBAAkB,iBACT,qBAAqB,EAAE;IAEtC;;;;;;;;;;;OAWG;;;;;;;;;;IAsDH;;;;;;;;;OASG;;CA4EH,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,sBAAsB,UAC1B,KAAK,sBACQ,sBAAsB,EAAE,SA6D7C,CAAA"}