run-script: Add option to ignore the current node executable for PATH

Add a `--scripts-prepend-node-path` option that controls `npm`’s
behaviour with respect to adding the directory of
the current `node` executable to the `PATH`, even if that means
that `npm` will invoke a different `node` executable than the
one which it is running.

This is a non-invasive solution to some of the problems described in
https://github.com/npm/npm/issues/12318. It should not come with
any drawbacks for npm’s side, as it shifts the responsibility of
making sure that the `PATH` variable contains everything it should
to whoever invoked npm with `--scripts-prepend-node-path=false`.

While https://github.com/npm/npm/pull/12968 may have addressed some
of the problems described there, it does not help in the case that
the `PATH` has explicitly been overridden with the intention of
having a different `node` executed.

[squash] test: anticipate coverage tooling possibly setting --scripts-prepend-node-path

As one of the motivations for introducing `--scripts-prepend-node-path`
is that `spawn-wrap` (which npm itself uses for coverage) can make use
of that option, anticipate that change in order to not break the
test suite when updating that dependency at a later point.

[squash] tests for scripts-prepend-node-path=auto

[squash] implement `warn-only` setting for `--scripts-prepend-node-path`

Adds a setting that is basically equivalent to `--scripts-prepend-node-path=false`
but emits a warning informing the user about the existence of the
option in the cases in which `npm` currently modifies `PATH`,
as sometimes that’s in the user’s interest.

[squash] fixup tests for windows

PR-URL: https://github.com/npm/npm/pull/13409
Credit: @addaleax
Reviewed-By: @zkat
Reviewed-By: @othiym23

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/misc/npm-config.md b/doc/misc/npm-config.md
index 343a798b6..3803cb114 100644
--- a/doc/misc/npm-config.md
+++ b/doc/misc/npm-config.md
@@ -810,6 +810,26 @@ in to a private registry for the first time:
 will cause `@organization` to be mapped to the registry for future installation
 of packages specified according to the pattern `@organization/package`.
 
+### scripts-prepend-node-path
+
+* Default: "auto"
+* Type: Boolean, `"auto"` or `"warn-only"`
+
+If set to `true`, add the directory in which the current `node` executable
+resides to the `PATH` environment variable when running scripts,
+even if that means that `npm` will invoke a different `node` executable than
+the one which it is running.
+
+If set to `false`, never modify `PATH` with that.
+
+If set to `"warn-only"`, never modify `PATH` but print a warning if `npm` thinks
+that you may want to run it with `true`, e.g. because the `node` executable
+in the `PATH` is not the one `npm` was invoked with.
+
+If set to `auto`, only add that directory to the `PATH` environment variable
+if the `node` executable with which `npm` was invoked and the one that is found
+first on the `PATH` are different.
+
 ### searchexclude
 
 * Default: ""