@pnpm/deps.graph-hasher 1100.1.4 → 1100.2.0

package/lib/index.d.ts

@@ -1,5 +1,44 @@
 import type { LockfileObject, LockfileResolution, PackageSnapshot } from '@pnpm/lockfile.types';
 import type { AllowBuild, DepPath, PkgIdWithPatchHash, SupportedArchitectures } from '@pnpm/types';
+/**
+ * Scan an iterable of lockfile snapshot keys for the resolved
+ * `engines.runtime` / `devEngines.runtime` Node version and return
+ * its bare version string (e.g. `"22.11.0"`), or `undefined` when
+ * no snapshot pins a runtime.
+ *
+ * Pnpm's runtime resolver writes the pinned Node into the lockfile as
+ * a snapshot with key `node@runtime:<version>[(<peers>)]`
+ * (see [`engine/runtime/node-resolver/src/index.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/engine/runtime/node-resolver/src/index.ts)).
+ * The first such key found is treated as authoritative. This is fine
+ * as an install-wide fallback (project-pin in the typical case), but
+ * snapshots that pin their own Node still need
+ * {@link readSnapshotRuntimePin} to get a per-snapshot result.
+ *
+ * Callers typically pass `Object.keys(lockfile.packages ?? {})` — the
+ * in-memory `LockfileObject` merges the on-disk `packages:` and
+ * `snapshots:` sections under a single `packages` field, so its keys
+ * include every snapshot key the install will hash.
+ */
+export declare function findRuntimeNodeVersion(snapshotKeys: Iterable<string>): string | undefined;
+/**
+ * Read a single graph node's own `engines.runtime` Node pin from its
+ * `children` map. The resolver desugars `engines.runtime` declared on
+ * a dependency's manifest into `dependencies.node: 'runtime:<version>'`
+ * (see [`installing/deps-resolver/src/resolveDependencies.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/installing/deps-resolver/src/resolveDependencies.ts)),
+ * which then becomes a `children.node` entry pointing at the
+ * `node@runtime:<version>[(peers)]` snapshot key.
+ *
+ * Returns the bare version (e.g. `"22.11.0"`) when this snapshot pins
+ * its own Node — or `undefined` when it doesn't and the caller should
+ * fall back to the install-wide pin / host probe.
+ *
+ * Per-snapshot resolution matters because the bin linker routes
+ * lifecycle-script spawns for a pinning package through *that
+ * package's* downloaded Node — anchoring the snapshot's GVS engine
+ * hash to an install-wide value would produce the wrong
+ * side-effects-cache key for cross-pinning installs.
+ */
+export declare function readSnapshotRuntimePin(children: Record<string, string> | undefined): string | undefined;
 export type DepsGraph<T extends string> = Record<T, DepsGraphNode<T>>;
 export interface DepsGraphNode<T extends string> {
     children: {
@@ -16,6 +55,17 @@ export declare function calcDepState<T extends string>(depsGraph: DepsGraph<T>,
     patchFileHash?: string;
     includeDepGraphHash: boolean;
     supportedArchitectures?: SupportedArchitectures;
+    /**
+     * Install-wide fallback `engines.runtime` / `devEngines.runtime`
+     * Node version (e.g. `"22.11.0"`). Used only when the snapshot at
+     * `depPath` doesn't itself pin a Node: per-snapshot pins take
+     * precedence so the side-effects-cache key reflects the actual
+     * script-runner Node the bin linker would spawn for the package
+     * (see {@link readSnapshotRuntimePin}). Typically computed once
+     * per install via {@link findRuntimeNodeVersion} over the
+     * lockfile's snapshot keys.
+     */
+    nodeVersion?: string;
 }): string;
 export interface PkgMeta {
     depPath: DepPath;
@@ -27,13 +77,28 @@ export interface HashedDepPath<T extends PkgMeta> {
     pkgMeta: T;
     hash: string;
 }
-export declare function iterateHashedGraphNodes<T extends PkgMeta>(graph: DepsGraph<DepPath>, pkgMetaIterator: PkgMetaIterator<T>, allowBuild?: AllowBuild, supportedArchitectures?: SupportedArchitectures): IterableIterator<HashedDepPath<T>>;
-export declare function calcGraphNodeHash<T extends PkgMeta>({ graph, cache, builtDepPaths, buildRequiredCache, supportedArchitectures }: {
+export declare function iterateHashedGraphNodes<T extends PkgMeta>(graph: DepsGraph<DepPath>, pkgMetaIterator: PkgMetaIterator<T>, allowBuild?: AllowBuild, supportedArchitectures?: SupportedArchitectures, 
+/**
+ * Install-wide fallback `engines.runtime` / `devEngines.runtime`
+ * Node version. Used only for snapshots that don't pin their own
+ * Node; pinning snapshots get resolved per-snapshot via
+ * {@link readSnapshotRuntimePin} so the GVS engine hash matches
+ * the Node the bin linker would actually spawn for each package
+ * (see [`bins/linker/src/index.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/bins/linker/src/index.ts)).
+ * Typically obtained via {@link findRuntimeNodeVersion} over the
+ * lockfile's snapshot keys. `undefined` falls back to
+ * {@link engineName}'s default (system `node --version`, with
+ * `process.version` as a last resort).
+ */
+nodeVersion?: string): IterableIterator<HashedDepPath<T>>;
+export declare function calcGraphNodeHash<T extends PkgMeta>({ graph, cache, builtDepPaths, buildRequiredCache, supportedArchitectures, nodeVersion }: {
     graph: DepsGraph<DepPath>;
     cache: DepsStateCache;
     builtDepPaths?: Set<DepPath>;
     buildRequiredCache?: Record<string, boolean>;
     supportedArchitectures?: SupportedArchitectures;
+    /** See [`iterateHashedGraphNodes`]'s `nodeVersion` parameter. */
+    nodeVersion?: string;
 }, pkgMeta: T): string;
 export declare function calcLeafGlobalVirtualStorePath(fullPkgId: string, name: string, version: string): string;
 export interface PkgMetaAndSnapshot extends PkgMeta {

package/lib/index.js

@@ -1,11 +1,78 @@
-import { ENGINE_NAME } from '@pnpm/constants';
 import { hashObject, hashObjectWithoutSorting } from '@pnpm/crypto.object-hasher';
 import { getPkgIdWithPatchHash, refToRelative } from '@pnpm/deps.path';
+import { engineName } from '@pnpm/engine.runtime.system-node-version';
 import { nameVerFromPkgSnapshot } from '@pnpm/lockfile.utils';
 import { resolvePlatformSelector, selectPlatformVariant } from '@pnpm/resolving.resolver-base';
 import { familySync } from 'detect-libc';
+/**
+ * Strip the `node@runtime:` prefix and any peer-context suffix `(...)`
+ * from a single snapshot key, returning the bare Node version (e.g.
+ * `"22.11.0"`) — or `undefined` if the key isn't a Node runtime pin.
+ *
+ * Peer-suffixed (`node@runtime:22.11.0(node@22.11.0)`) and bare
+ * (`node@runtime:22.11.0`) forms must reduce to the same answer; the
+ * pacquet side relies on the same rule for GVS-hash parity.
+ */
+function extractRuntimeNodeVersion(snapshotKey) {
+    const prefix = 'node@runtime:';
+    if (!snapshotKey.startsWith(prefix))
+        return undefined;
+    const versionWithPeers = snapshotKey.slice(prefix.length);
+    const parenAt = versionWithPeers.indexOf('(');
+    return parenAt === -1 ? versionWithPeers : versionWithPeers.slice(0, parenAt);
+}
+/**
+ * Scan an iterable of lockfile snapshot keys for the resolved
+ * `engines.runtime` / `devEngines.runtime` Node version and return
+ * its bare version string (e.g. `"22.11.0"`), or `undefined` when
+ * no snapshot pins a runtime.
+ *
+ * Pnpm's runtime resolver writes the pinned Node into the lockfile as
+ * a snapshot with key `node@runtime:<version>[(<peers>)]`
+ * (see [`engine/runtime/node-resolver/src/index.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/engine/runtime/node-resolver/src/index.ts)).
+ * The first such key found is treated as authoritative. This is fine
+ * as an install-wide fallback (project-pin in the typical case), but
+ * snapshots that pin their own Node still need
+ * {@link readSnapshotRuntimePin} to get a per-snapshot result.
+ *
+ * Callers typically pass `Object.keys(lockfile.packages ?? {})` — the
+ * in-memory `LockfileObject` merges the on-disk `packages:` and
+ * `snapshots:` sections under a single `packages` field, so its keys
+ * include every snapshot key the install will hash.
+ */
+export function findRuntimeNodeVersion(snapshotKeys) {
+    for (const key of snapshotKeys) {
+        const version = extractRuntimeNodeVersion(key);
+        if (version != null)
+            return version;
+    }
+    return undefined;
+}
+/**
+ * Read a single graph node's own `engines.runtime` Node pin from its
+ * `children` map. The resolver desugars `engines.runtime` declared on
+ * a dependency's manifest into `dependencies.node: 'runtime:<version>'`
+ * (see [`installing/deps-resolver/src/resolveDependencies.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/installing/deps-resolver/src/resolveDependencies.ts)),
+ * which then becomes a `children.node` entry pointing at the
+ * `node@runtime:<version>[(peers)]` snapshot key.
+ *
+ * Returns the bare version (e.g. `"22.11.0"`) when this snapshot pins
+ * its own Node — or `undefined` when it doesn't and the caller should
+ * fall back to the install-wide pin / host probe.
+ *
+ * Per-snapshot resolution matters because the bin linker routes
+ * lifecycle-script spawns for a pinning package through *that
+ * package's* downloaded Node — anchoring the snapshot's GVS engine
+ * hash to an install-wide value would produce the wrong
+ * side-effects-cache key for cross-pinning installs.
+ */
+export function readSnapshotRuntimePin(children) {
+    const ref = children?.node;
+    return ref != null ? extractRuntimeNodeVersion(ref) : undefined;
+}
 export function calcDepState(depsGraph, cache, depPath, opts) {
-    let result = ENGINE_NAME;
+    const ownPin = readSnapshotRuntimePin(depsGraph[depPath]?.children);
+    let result = engineName(ownPin ?? opts.nodeVersion);
     if (opts.includeDepGraphHash) {
         const depGraphHash = calcDepGraphHash(depsGraph, cache, new Set(), depPath, opts.supportedArchitectures);
         result += `;deps=${depGraphHash}`;
@@ -46,7 +113,20 @@ function calcDepGraphHash(depsGraph, cache, parents, depPath, supportedArchitect
     });
     return cache[depPath];
 }
-export function* iterateHashedGraphNodes(graph, pkgMetaIterator, allowBuild, supportedArchitectures) {
+export function* iterateHashedGraphNodes(graph, pkgMetaIterator, allowBuild, supportedArchitectures, 
+/**
+ * Install-wide fallback `engines.runtime` / `devEngines.runtime`
+ * Node version. Used only for snapshots that don't pin their own
+ * Node; pinning snapshots get resolved per-snapshot via
+ * {@link readSnapshotRuntimePin} so the GVS engine hash matches
+ * the Node the bin linker would actually spawn for each package
+ * (see [`bins/linker/src/index.ts`](https://github.com/pnpm/pnpm/blob/29a42efc3b/bins/linker/src/index.ts)).
+ * Typically obtained via {@link findRuntimeNodeVersion} over the
+ * lockfile's snapshot keys. `undefined` falls back to
+ * {@link engineName}'s default (system `node --version`, with
+ * `process.version` as a last resort).
+ */
+nodeVersion) {
     let builtDepPaths;
     let entries;
     if (allowBuild != null) {
@@ -63,6 +143,7 @@ export function* iterateHashedGraphNodes(graph, pkgMetaIterator, allowBuild, sup
         builtDepPaths,
         buildRequiredCache: builtDepPaths !== undefined ? {} : undefined,
         supportedArchitectures,
+        nodeVersion,
     };
     for (const pkgMeta of entries) {
         yield {
@@ -71,7 +152,7 @@ export function* iterateHashedGraphNodes(graph, pkgMetaIterator, allowBuild, sup
         };
     }
 }
-export function calcGraphNodeHash({ graph, cache, builtDepPaths, buildRequiredCache, supportedArchitectures }, pkgMeta) {
+export function calcGraphNodeHash({ graph, cache, builtDepPaths, buildRequiredCache, supportedArchitectures, nodeVersion }, pkgMeta) {
     const { name, version, depPath } = pkgMeta;
     // When builtDepPaths is provided (derived from the allowBuilds config),
     // we only include the engine name for packages that are allowed to build
@@ -80,7 +161,13 @@ export function calcGraphNodeHash({ graph, cache, builtDepPaths, buildRequiredCa
     // so they survive Node.js upgrades and architecture changes.
     const includeEngine = builtDepPaths === undefined ||
         transitivelyRequiresBuild(graph, builtDepPaths, buildRequiredCache ??= {}, depPath, new Set());
-    const engine = includeEngine ? ENGINE_NAME : null;
+    // A snapshot that declares `engines.runtime` carries the desugared
+    // `node@runtime:<version>` pin as a child; that's the Node the bin
+    // linker spawns for its lifecycle scripts, so it has to drive the
+    // engine portion of the hash too. Non-pinning siblings fall through
+    // to the install-wide value.
+    const ownPin = readSnapshotRuntimePin(graph[depPath]?.children);
+    const engine = includeEngine ? engineName(ownPin ?? nodeVersion) : null;
     const deps = calcDepGraphHash(graph, cache, new Set(), depPath, supportedArchitectures);
     const hexDigest = hashObjectWithoutSorting({ engine, deps }, { encoding: 'hex' });
     return formatGlobalVirtualStorePath(name, version, hexDigest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/deps.graph-hasher",
-  "version": "1100.1.4",
+  "version": "1100.2.0",
   "description": "Calculates the state of a dependency",
   "keywords": [
     "pnpm",
@@ -24,18 +24,18 @@
     "!*.map"
   ],
   "dependencies": {
-    "detect-libc": "^2.1.2",
-    "@pnpm/constants": "1100.0.0",
-    "@pnpm/deps.path": "1100.0.2",
-    "@pnpm/lockfile.types": "1100.0.4",
-    "@pnpm/resolving.resolver-base": "1100.1.2",
+    "detect-libc": "^2.0.3",
     "@pnpm/crypto.object-hasher": "1100.0.0",
-    "@pnpm/lockfile.utils": "1100.0.6",
-    "@pnpm/types": "1101.0.0"
+    "@pnpm/deps.path": "1100.0.3",
+    "@pnpm/lockfile.types": "1100.0.6",
+    "@pnpm/engine.runtime.system-node-version": "1100.1.0",
+    "@pnpm/resolving.resolver-base": "1100.2.0",
+    "@pnpm/types": "1101.1.0",
+    "@pnpm/lockfile.utils": "1100.0.8"
   },
   "devDependencies": {
     "@jest/globals": "30.3.0",
-    "@pnpm/deps.graph-hasher": "1100.1.4"
+    "@pnpm/deps.graph-hasher": "1100.2.0"
   },
   "engines": {
     "node": ">=22.13"