fix: npm update --save (#4223)

Previously `npm update` was not respecting the `save` option, it
would be impossible for users to use `npm update` and automatically
update their `package.json` files.

This fixes it by adding extra steps on `Arborist.reify._saveIdealTree`
to read direct dependencies of any `package.json` and update them as
needed when reifying using the `update` and `save` options.

- Uses config.isDefault to set a different value for the `save` config
  for both the update and dedupe commands
- Tweaks arborist to make sure saveIdealTree preserves the behavior of
  skipping writing to package-lock.json on save=false for install while
  still writing the lockfile for `npm update` with its new default value
  of save=false.
- Updated and added some new tests on arborist to cover for these tweaks
- Added `npm update --save` smoke test on cli

Fixes: https://github.com/npm/cli/issues/708
Fixes: https://github.com/npm/cli/issues/2704
Relates to: https://github.com/npm/feedback/discussions/270

3 files changed, 18 insertions, 3 deletions

diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md
index 377e17d81..53d2e6427 100644
--- a/docs/content/commands/npm-dedupe.md
+++ b/docs/content/commands/npm-dedupe.md
@@ -72,6 +72,12 @@ result in new modules being installed.
 
 Using `npm find-dupes` will run the command in `--dry-run` mode.
 
+Note that by default `npm dedupe` will not update the semver values of direct
+dependencies in your project `package.json`, if you want to also update
+values in `package.json` you can run: `npm dedupe --save` (or add the
+`save=true` option to a [configuration file](/configuring-npm/npmrc)
+to make that the default behavior).
+
 ### Configuration
 
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md
index ad02118e4..1889d6056 100644
--- a/docs/content/commands/npm-update.md
+++ b/docs/content/commands/npm-update.md
@@ -27,6 +27,12 @@ packages.
 If no package name is specified, all packages in the specified location (global
 or local) will be updated.
 
+Note that by default `npm update` will not update the semver values of direct
+dependencies in your project `package.json`, if you want to also update
+values in `package.json` you can run: `npm update --save` (or add the
+`save=true` option to a [configuration file](/configuring-npm/npmrc)
+to make that the default behavior).
+
 ### Example
 
 For the examples below, assume that the current package is `app` and it depends
diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index fe197e344..83a385e08 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -1326,13 +1326,16 @@ The base URL of the npm registry.
 
 #### `save`
 
-* Default: true
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
 * Type: Boolean
 
-Save installed packages to a package.json file as dependencies.
+Save installed packages to a `package.json` file as dependencies.
 
 When used with the `npm rm` command, removes the dependency from
-package.json.
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->