fix(env): stop inherited pin lookup at nearer runtime constraints

Author: ywenhao

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_env_pin_nvmrc/snapshots.toml

@@ -112,6 +112,20 @@ steps = [
   ["vpt", "print-file", ".nvmrc", "package.json"],
 ]
 
+[[case]]
+name = "engines_node_stops_inherited_pin_lookup"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "mkdir", "-p", "middle/leaf"], snapshot = false },
+  { argv = ["vpt", "write-file", "middle/package.json", "{\"engines\":{\"node\":\"22.13.0\"}}\n"], snapshot = false },
+  { argv = ["vp", "env", "pin"], cwd = "middle/leaf", comment = "the nearer engines.node prevents inheriting the root .nvmrc" },
+  { argv = ["vp", "env", "current", "node", "--json"], cwd = "middle/leaf" },
+  { argv = ["vp", "env", "pin"], cwd = "middle", comment = "a constraint in cwd also prevents reporting an ancestor pin" },
+  { argv = ["vp", "env", "current", "node", "--json"], cwd = "middle" },
+  ["vpt", "print-file", ".nvmrc", "middle/package.json"],
+]
+
 [[case]]
 name = "nvmrc_target_rejects_package_manager_operations"
 vp = "global"

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_env_pin_nvmrc/snapshots/engines_node_stops_inherited_pin_lookup.md

@@ -0,0 +1,74 @@
+# engines_node_stops_inherited_pin_lookup
+
+## `vpt mkdir -p middle/leaf`
+
+
+## `vpt write-file middle/package.json '{"engines":{"node":"22.13.0"}}
+'`
+
+
+## `cd middle/leaf && vp env pin`
+
+the nearer engines.node prevents inheriting the root .nvmrc
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+No version pinned.
+  Node.js constraint: 22.13.0 from <workspace>/middle/package.json (engines.node)
+
+No package manager pinned.
+```
+
+## `cd middle/leaf && vp env current node --json`
+
+```
+{
+  "node": {
+    "version": "22.13.0",
+    "source": "engines.node",
+    "source_path": "<workspace>/middle/package.json",
+    "project_root": "<workspace>/middle",
+    "bin_path": "<home>/.vite-plus/js_runtime/node/<version>/bin/node",
+    "installed": false,
+    "mode": "managed"
+  }
+}
+```
+
+## `cd middle && vp env pin`
+
+a constraint in cwd also prevents reporting an ancestor pin
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+No version pinned.
+  Node.js constraint: 22.13.0 from <workspace>/middle/package.json (engines.node)
+
+No package manager pinned.
+```
+
+## `cd middle && vp env current node --json`
+
+```
+{
+  "node": {
+    "version": "22.13.0",
+    "source": "engines.node",
+    "source_path": "<workspace>/middle/package.json",
+    "project_root": "<workspace>/middle",
+    "bin_path": "<home>/.vite-plus/js_runtime/node/<version>/bin/node",
+    "installed": false,
+    "mode": "managed"
+  }
+}
+```
+
+## `vpt print-file .nvmrc middle/package.json`
+
+```
+# Node for local tools and CI
+<version> # keep this comment
+{"engines":{"node":"22.13.0"}}
+```

crates/vp_global_cli/src/commands/env/pin.rs

@@ -137,12 +137,24 @@ async fn show_pinned(cwd: &AbsolutePathBuf) -> Result<ExitStatus, Error> {
         return Ok(ExitStatus::default());
     }
 
-    if let Some(resolution) = resolve_node_version(cwd, false).await?
-        && resolution.source == VersionSource::NvmrcFile
-    {
-        println!("Pinned version: {}", resolution.version);
-        println!("  Source: {}", cwd.join(NVMRC_FILE).as_path().display());
-        return Ok(ExitStatus::default());
+    if let Some(resolution) = resolve_node_version(cwd, true).await? {
+        if resolution.source == VersionSource::NvmrcFile
+            && resolution.project_root.as_ref() == Some(cwd)
+        {
+            println!("Pinned version: {}", resolution.version);
+            println!("  Source: {}", cwd.join(NVMRC_FILE).as_path().display());
+            return Ok(ExitStatus::default());
+        }
+        if resolution.source == VersionSource::EnginesNode {
+            let path = resolution.source_path.unwrap_or_else(|| cwd.join(PACKAGE_JSON_FILE));
+            println!("No version pinned.");
+            println!(
+                "  Node.js constraint: {} from {} (engines.node)",
+                resolution.version,
+                path.as_path().display()
+            );
+            return Ok(ExitStatus::default());
+        }
     }
 
     // Check for inherited version from parent directories
@@ -194,13 +206,16 @@ async fn find_inherited_version(cwd: &AbsolutePathBuf) -> Result<Option<(String,
                 format!("{} (devEngines.runtime)", dir.join(PACKAGE_JSON_FILE).as_path().display()),
             )));
         }
-        if let Some(resolution) = resolve_node_version(&dir, false).await?
-            && resolution.source == VersionSource::NvmrcFile
-        {
-            return Ok(Some((
-                resolution.version.to_string(),
-                dir.join(NVMRC_FILE).as_path().display().to_string(),
-            )));
+        if let Some(resolution) = resolve_node_version(&dir, false).await? {
+            if resolution.source == VersionSource::NvmrcFile {
+                return Ok(Some((
+                    resolution.version.to_string(),
+                    dir.join(NVMRC_FILE).as_path().display().to_string(),
+                )));
+            }
+            // A nearer runtime constraint blocks more distant pins, even if
+            // this command does not treat that source as a writable pin.
+            return Ok(None);
         }
         current = dir.parent().map(|p| p.to_absolute_path_buf());
     }
@@ -1254,6 +1269,28 @@ mod tests {
         assert!(source.ends_with("package.json (devEngines.runtime)"), "got: {source}");
     }
 
+    #[tokio::test]
+    async fn test_find_inherited_version_stops_at_nearer_engines_node() {
+        let temp_dir = TempDir::new().unwrap();
+        let root = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        let middle = root.join("middle");
+        let leaf = middle.join("leaf");
+        tokio::fs::create_dir_all(&leaf).await.unwrap();
+        tokio::fs::write(root.join(".nvmrc"), "20.18.0\n").await.unwrap();
+        tokio::fs::write(middle.join("package.json"), r#"{"engines":{"node":"22.13.0"}}"#)
+            .await
+            .unwrap();
+
+        let runtime = resolve_node_version(&leaf, true).await.unwrap().unwrap();
+        assert_eq!(runtime.source, VersionSource::EnginesNode);
+        assert!(find_inherited_version(&leaf).await.unwrap().is_none());
+
+        tokio::fs::remove_file(middle.join("package.json")).await.unwrap();
+        let (version, source) = find_inherited_version(&leaf).await.unwrap().unwrap();
+        assert_eq!(version, "20.18.0");
+        assert!(source.ends_with(".nvmrc"));
+    }
+
     #[tokio::test]
     async fn test_find_inherited_version_node_version_wins_over_dev_engines() {
         let temp_dir = TempDir::new().unwrap();

rfcs/dev-engines.md

@@ -207,7 +207,7 @@ When `.node-version` is the write target and a `devEngines.runtime` node entry a
 
 #### 2.5 `vp env pin` (show) and `vp env unpin`
 
-- `vp env pin` with no argument reports the active pin and its source, including an effective `.nvmrc`. Inherited pins from parent directories are reported in the same order: `.node-version`, the `devEngines.runtime` node entry, then an effective `.nvmrc`.
+- `vp env pin` with no argument reports the active pin and its source, including an effective `.nvmrc`. Inherited pins from parent directories are reported in the same order: `.node-version`, the `devEngines.runtime` node entry, then an effective `.nvmrc`. A nearer `engines.node` stops the search and is displayed as a runtime constraint rather than inheriting a more distant pin.
 - `vp env unpin` / `vp env pin --unpin` removes the pin from the same target that `vp env pin` would write: delete `.node-version` if present, delete an effective `.nvmrc` in cwd, or remove the node entry from `devEngines.runtime` (removing the `devEngines.runtime` key entirely if it becomes empty, and `devEngines` if it becomes empty). An explicit `--target nvmrc` removes that file even if another source shadows it. Parent-directory files are never removed.
 
 ### 3. Package manager