deps: upgrade npm to 7.1.2

deps/npm/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 7.1.2 (2020-12-11)
+
+### DEPENDENCIES
+
+* [`c3ba1daf7`](https://github.com/npm/cli/commit/c3ba1daf7cd335d72aeba80ae0e9f9d215ca9ea5)
+  [#2033](https://github.com/npm/cli/issues/2033) `@npmcli/config@1.2.6`:
+    * Set `INIT_CWD` to initial current working directory
+    * Set `NODE` to initial process.execPath
+* [`8029608b9`](https://github.com/npm/cli/commit/8029608b914fe5ba35a7cd37ae95ab93b0532e2e)
+  `json-parse-even-better-errors@2.3.1`
+* [`0233818e6`](https://github.com/npm/cli/commit/0233818e606888b80881b17a2c6aca9f10a619b2)
+  [#2332](https://github.com/npm/cli/issues/2332) `treeverse@1.0.4`
+* [`e401d6bb3`](https://github.com/npm/cli/commit/e401d6bb37ffc767b4fefe89878dd3c3ef490b2c)
+  `ini@1.3.8`
+* [`011bb1220`](https://github.com/npm/cli/commit/011bb122035dcd43769ec35982662cca41635068)
+  [#2320](https://github.com/npm/cli/issues/2320) `@npmcli/arborist@2.0.1`:
+    * Do not save with `^` and no version
+
+### BUGFIXES
+
+* [`244c2069f`](https://github.com/npm/cli/commit/244c2069fd093f053d3061c85575ac13e72e2454)
+  [#2325](https://github.com/npm/cli/issues/2325) npm search
+  include/exclude ([@ruyadorno](https://github.com/ruyadorno))
+* [`d825e901e`](https://github.com/npm/cli/commit/d825e901eceea4cf8d860e35238dc30008eb4da4)
+  [#1905](https://github.com/npm/cli/issues/1905)
+  [#2316](https://github.com/npm/cli/issues/2316) run install scripts for
+  root project
+* [`315449142`](https://github.com/npm/cli/commit/31544914294948085a84097af7f0f5de2a2e8f7e)
+  [#2331](https://github.com/npm/cli/issues/2331)
+  [#2021](https://github.com/npm/cli/issues/2021) Set `NODE_ENV=production`
+  if 'dev' is on the omit list ([@isaacs](https://github.com/isaacs))
+
+### TESTING
+
+* [`c243e3b9d`](https://github.com/npm/cli/commit/c243e3b9d9bda0580a0fc1b3e230b4d47412176e)
+  [#2313](https://github.com/npm/cli/issues/2313) tests: completion
+  ([@nlf](https://github.com/nlf))
+* [`7ff6efbb8`](https://github.com/npm/cli/commit/7ff6efbb866591b2330b967215cef8146dff3ebf)
+  [#2314](https://github.com/npm/cli/issues/2314) npm team
+  ([@ruyadorno](https://github.com/ruyadorno))
+* [`7a4f0c96c`](https://github.com/npm/cli/commit/7a4f0c96c2ab9f264f7bda2caf7e72c881571270)
+  [#2323](https://github.com/npm/cli/issues/2323) npm doctor
+  ([@nlf](https://github.com/nlf))
+
+### DOCUMENTATION
+
+* [`e340cf64b`](https://github.com/npm/cli/commit/e340cf64ba31ef329a9049b60c32ffd0342cfb7d)
+  [#2330](https://github.com/npm/cli/issues/2330) explain through
+  run-script ([@isaacs](https://github.com/isaacs))
+
 ## 7.1.1 (2020-12-08)
 
 ### DEPENDENCIES

deps/npm/docs/content/commands/npm-explain.md

@@ -8,6 +8,8 @@ description: Explain installed packages
 
 ```bash
 npm explain <folder | specifier>
+
+alias: why
 ```
 
 ### Description

deps/npm/docs/content/commands/npm-link.md

@@ -15,41 +15,44 @@ alias: npm ln
 
 ### Description
 
+This is handy for installing your own stuff, so that you can work on it and
+test iteratively without having to continually rebuild.
+
 Package linking is a two-step process.
 
-First, `npm link` in a package folder will create a symlink in the global folder
-`{prefix}/lib/node_modules/<package>` that links to the package where the `npm
-link` command was executed. It will also link any bins in the package to `{prefix}/bin/{name}`.
-Note that `npm link` uses the global prefix (see `npm prefix -g` for its value).
+First, `npm link` in a package folder will create a symlink in the global
+folder `{prefix}/lib/node_modules/<package>` that links to the package
+where the `npm link` command was executed. It will also link any bins in
+the package to `{prefix}/bin/{name}`.  Note that `npm link` uses the global
+prefix (see `npm prefix -g` for its value).
 
 Next, in some other location, `npm link package-name` will create a
-symbolic link from globally-installed `package-name` to `node_modules/`
-of the current folder.
+symbolic link from globally-installed `package-name` to `node_modules/` of
+the current folder.
 
-Note that `package-name` is taken from `package.json`,
-not from directory name.
+Note that `package-name` is taken from `package.json`, _not_ from the
+directory name.
 
-The package name can be optionally prefixed with a scope. See [`scope`](/using-npm/scope).
-The scope must be preceded by an @-symbol and followed by a slash.
+The package name can be optionally prefixed with a scope. See
+[`scope`](/using-npm/scope).  The scope must be preceded by an @-symbol and
+followed by a slash.
 
 When creating tarballs for `npm publish`, the linked packages are
-"snapshotted" to their current state by resolving the symbolic links.
-
-This is handy for installing your own stuff, so that you can work on it and
-test it iteratively without having to continually rebuild.
+"snapshotted" to their current state by resolving the symbolic links, if
+they are included in `bundleDependencies`.
 
 For example:
 
 ```bash
-    cd ~/projects/node-redis    # go into the package directory
-    npm link                    # creates global link
-    cd ~/projects/node-bloggy   # go into some other package directory.
-    npm link redis              # link-install the package
+cd ~/projects/node-redis    # go into the package directory
+npm link                    # creates global link
+cd ~/projects/node-bloggy   # go into some other package directory.
+npm link redis              # link-install the package
 ```
 
-Now, any changes to ~/projects/node-redis will be reflected in
-~/projects/node-bloggy/node_modules/node-redis/. Note that the link should
-be to the package name, not the directory name for that package.
+Now, any changes to `~/projects/node-redis` will be reflected in
+`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link
+should be to the package name, not the directory name for that package.
 
 You may also shortcut the two steps in one.  For example, to do the
 above use-case in a shorter way:
@@ -69,15 +72,33 @@ npm link redis
 That is, it first creates a global link, and then links the global
 installation target into your project's `node_modules` folder.
 
-Note that in this case, you are referring to the directory name, `node-redis`,
-rather than the package name `redis`.
+Note that in this case, you are referring to the directory name,
+`node-redis`, rather than the package name `redis`.
 
-If your linked package is scoped (see [`scope`](/using-npm/scope)) your link command must include that scope, e.g.
+If your linked package is scoped (see [`scope`](/using-npm/scope)) your
+link command must include that scope, e.g.
 
 ```bash
 npm link @myorg/privatepackage
 ```
 
+### Caveat
+
+Note that package dependencies linked in this way are _not_ saved to
+`package.json` by default, on the assumption that the intention is to have
+a link stand in for a regular non-link dependency.  Otherwise, for example,
+if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace
+the `^3.0.1` dependency with `file:../path/to/node-redis`, which you
+probably don't want!  Additionally, other users or developers on your
+project would run into issues if they do not have their folders set up
+exactly the same as yours.
+
+If you are adding a _new_ dependency as a link, you should add it to the
+relevant metadata by running `npm install <dep> --package-lock-only`.
+
+If you _want_ to save the `file:` reference in your `package.json` and
+`package-lock.json` files, you can use `npm link <dep> --save` to do so.
+
 ### See Also
 
 * [npm developers](/using-npm/developers)

deps/npm/docs/content/commands/npm-logout.md

@@ -12,13 +12,13 @@ npm logout [--registry=<url>] [--scope=<@scope>]
 
 ### Description
 
-When logged into a registry that supports token-based authentication, tell the
-server to end this token's session. This will invalidate the token everywhere
-you're using it, not just for the current environment.
+When logged into a registry that supports token-based authentication, tell
+the server to end this token's session. This will invalidate the token
+everywhere you're using it, not just for the current environment.
 
-When logged into a legacy registry that uses username and password authentication, this will
-clear the credentials in your user configuration. In this case, it will _only_ affect
-the current environment.
+When logged into a legacy registry that uses username and password
+authentication, this will clear the credentials in your user configuration.
+In this case, it will _only_ affect the current environment.
 
 If `--scope` is provided, this will find the credentials for the registry
 connected to that scope, if set.

deps/npm/docs/content/commands/npm-ls.md

@@ -15,17 +15,21 @@ aliases: list, la, ll
 ### Description
 
 This command will print to stdout all the versions of packages that are
-installed, as well as their dependencies, in a tree-structure.
+installed, as well as their dependencies when `--all` is specified, in a
+tree structure.
 
-Positional arguments are `name@version-range` identifiers, which will
-limit the results to only the paths to the packages named.  Note that
-nested packages will *also* show the paths to the specified packages.
-For example, running `npm ls promzard` in npm's source tree will show:
+Note: to get a "bottoms up" view of why a given package is included in the
+tree at all, use [`npm explain`](/commands/npm-explain).
+
+Positional arguments are `name@version-range` identifiers, which will limit
+the results to only the paths to the packages named.  Note that nested
+packages will *also* show the paths to the specified packages.  For
+example, running `npm ls promzard` in npm's source tree will show:
 
 ```bash
-    npm@@VERSION@ /path/to/npm
-    └─┬ init-package-json@0.0.4
-      └── promzard@0.1.5
+npm@@VERSION@ /path/to/npm
+└─┬ init-package-json@0.0.4
+  └── promzard@0.1.5
 ```
 
 It will print out extraneous, missing, and invalid packages.
@@ -35,12 +39,49 @@ in parentheses after the name@version to make it easier for users to
 recognize potential forks of a project.
 
 The tree shown is the logical dependency tree, based on package
-dependencies, not the physical layout of your node_modules folder.
+dependencies, not the physical layout of your `node_modules` folder.
 
 When run as `ll` or `la`, it shows extended information by default.
 
+### Note: Design Changes Pending
+
+The `npm ls` command's output and behavior made a _ton_ of sense when npm
+created a `node_modules` folder that naively nested every dependency.  In
+such a case, the logical dependency graph and physical tree of packages on
+disk would be roughly identical.
+
+With the advent of automatic install-time deduplication of dependencies in
+npm v3, the `ls` output was modified to display the logical dependency
+graph as a tree structure, since this was more useful to most users.
+However, without using `npm ls -l`, it became impossible show _where_ a
+package was actually installed much of the time!
+
+With the advent of automatic installation of `peerDependencies` in npm v7,
+this gets even more curious, as `peerDependencies` are logically
+"underneath" their dependents in the dependency graph, but are always
+physically at or above their location on disk.
+
+Also, in the years since npm got an `ls` command (in version 0.0.2!),
+dependency graphs have gotten much larger as a general rule.  Therefor, in
+order to avoid dumping an excessive amount of content to the terminal, `npm
+ls` now only shows the _top_ level dependencies, unless `--all` is
+provided.
+
+A thorough re-examination of the use cases, intention, behavior, and output
+of this command, is currently underway.  Expect significant changes to at
+least the default human-readable `npm ls` output in npm v8.
+
 ### Configuration
 
+#### all
+
+* Default: `false`
+* Type: Boolean
+
+When running `npm outdated` and `npm ls`, setting `--all` will show all
+outdated or installed packages, rather than only those directly depended
+upon by the current project.
+
 #### json
 
 * Default: false
@@ -115,6 +156,7 @@ Set it to false in order to use all-ansi output.
 
 ### See Also
 
+* [npm explain](/commands/npm-explain)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm folders](/configuring-npm/folders)

deps/npm/docs/content/commands/npm-org.md

@@ -52,10 +52,11 @@ $ npm org ls my-org @mx-santos
 
 ### Description
 
-You can use the `npm org` commands to manage and view users of an organization.
-It supports adding and removing users, changing their roles, listing them, and
-finding specific ones and their roles.
+You can use the `npm org` commands to manage and view users of an
+organization.  It supports adding and removing users, changing their roles,
+listing them, and finding specific ones and their roles.
 
 ### See Also
 
+* [using orgs](/using-npm/orgs)
 * [Documentation on npm Orgs](https://docs.npmjs.com/orgs/)

deps/npm/docs/content/commands/npm-outdated.md

@@ -15,25 +15,34 @@ npm outdated [[<@scope>/]<pkg> ...]
 This command will check the registry to see if any (or, specific) installed
 packages are currently outdated.
 
+By default, only the direct dependencies of the root project are shown.
+Use `--all` to find all outdated meta-dependencies as well.
+
 In the output:
 
 * `wanted` is the maximum version of the package that satisfies the semver
-  range specified in `package.json`. If there's no available semver range (i.e.
-  you're running `npm outdated --global`, or the package isn't included in
-  `package.json`), then `wanted` shows the currently-installed version.
+  range specified in `package.json`. If there's no available semver range
+  (i.e.  you're running `npm outdated --global`, or the package isn't
+  included in `package.json`), then `wanted` shows the currently-installed
+  version.
 * `latest` is the version of the package tagged as latest in the registry.
-  Running `npm publish` with no special configuration will publish the package
-  with a dist-tag of `latest`. This may or may not be the maximum version of
-  the package, or the most-recently published version of the package, depending
-  on how the package's developer manages the latest [dist-tag](npm-dist-tag).
+  Running `npm publish` with no special configuration will publish the
+  package with a dist-tag of `latest`. This may or may not be the maximum
+  version of the package, or the most-recently published version of the
+  package, depending on how the package's developer manages the latest
+  [dist-tag](/commands/npm-dist-tag).
 * `location` is where in the physical tree the package is located.
 * `depended by` shows which package depends on the displayed dependency
-* `package type` (when using `--long` / `-l`) tells you whether this package is
-  a `dependency` or a dev/peer/optional dependency. Packages not included in `package.json`
-  are always marked `dependencies`.
-* `homepage` (when using `--long` / `-l`) is the `homepage` value contained in the package's packument
-* Red means there's a newer version matching your semver requirements, so you should update now.
-* Yellow indicates that there's a newer version above your semver requirements (usually new major, or new 0.x minor) so proceed with caution.
+* `package type` (when using `--long` / `-l`) tells you whether this
+  package is a `dependency` or a dev/peer/optional dependency. Packages not
+  included in `package.json` are always marked `dependencies`.
+* `homepage` (when using `--long` / `-l`) is the `homepage` value contained
+  in the package's packument
+* Red means there's a newer version matching your semver requirements, so
+  you should update now.
+* Yellow indicates that there's a newer version _above_ your semver
+  requirements (usually new major, or new 0.x minor) so proceed with
+  caution.
 
 ### An example
 
@@ -59,19 +68,20 @@ With these `dependencies`:
 
 A few things to note:
 
-* `glob` requires `^5`, which prevents npm from installing `glob@6`, which is
-  outside the semver range.
-* Git dependencies will always be reinstalled, because of how they're specified.
-  The installed committish might satisfy the dependency specifier (if it's
-  something immutable, like a commit SHA), or it might not, so `npm outdated` and
-  `npm update` have to fetch Git repos to check. This is why currently doing a
-  reinstall of a Git dependency always forces a new clone and install.
-* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because npm
-  uses dist-tags to manage its `latest` and `next` release channels. `npm update`
-  will install the _newest_ version, but `npm install npm` (with no semver range)
-  will install whatever's tagged as `latest`.
-* `once` is just plain out of date. Reinstalling `node_modules` from scratch or
-  running `npm update` will bring it up to spec.
+* `glob` requires `^5`, which prevents npm from installing `glob@6`, which
+  is outside the semver range.
+* Git dependencies will always be reinstalled, because of how they're
+  specified.  The installed committish might satisfy the dependency
+  specifier (if it's something immutable, like a commit SHA), or it might
+  not, so `npm outdated` and `npm update` have to fetch Git repos to check.
+  This is why currently doing a reinstall of a Git dependency always forces
+  a new clone and install.
+* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because
+  npm uses dist-tags to manage its `latest` and `next` release channels.
+  `npm update` will install the _newest_ version, but `npm install npm`
+  (with no semver range) will install whatever's tagged as `latest`.
+* `once` is just plain out of date. Reinstalling `node_modules` from
+  scratch or running `npm update` will bring it up to spec.
 
 ### Configuration