deps: upgrade npm to 5.0.0

PR-URL: https://github.com/nodejs/node/pull/13276
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

10 files changed, 492 insertions, 243 deletions

diff --git a/deps/npm/doc/cli/npm-cache.md b/deps/npm/doc/cli/npm-cache.md
index ea8cb1b991..92a6236c0c 100644
--- a/deps/npm/doc/cli/npm-cache.md
+++ b/deps/npm/doc/cli/npm-cache.md
@@ -8,11 +8,11 @@ npm-cache(1) -- Manipulates packages cache
     npm cache add <tarball url>
     npm cache add <name>@<version>
 
-    npm cache ls [<path>]
-
     npm cache clean [<path>]
     aliases: npm cache clear, npm cache rm
 
+    npm cache verify
+
 ## DESCRIPTION
 
 Used to add, list, or clean the npm cache folder.
@@ -22,35 +22,45 @@ Used to add, list, or clean the npm cache folder.
   intended to be used internally by npm, but it can provide a way to
   add data to the local installation cache explicitly.
 
-* ls:
-  Show the data in the cache.  Argument is a path to show in the cache
-  folder.  Works a bit like the `find` program, but limited by the
-  `depth` config.
-
 * clean:
-  Delete data out of the cache folder.  If an argument is provided, then
-  it specifies a subpath to delete.  If no argument is provided, then
-  the entire cache is deleted.
+  Delete all data out of the cache folder.
+
+* verify:
+  Verify the contents of the cache folder, garbage collecting any unneeded data,
+  and verifying the integrity of the cache index and all cached data.
 
 ## DETAILS
 
-npm stores cache data in the directory specified in `npm config get cache`.
-For each package that is added to the cache, three pieces of information are
-stored in `{cache}/{name}/{version}`:
+npm stores cache data in an opaque directory within the configured `cache`,
+named `_cacache`. This directory is a `cacache`-based content-addressable cache
+that stores all http request data as well as other package-related data. This
+directory is primarily accessed through `pacote`, the library responsible for
+all package fetching as of npm@5.
+
+All data that passes through the cache is fully verified for integrity on both
+insertion and extraction. Cache corruption will either trigger an error, or
+signal to `pacote` that the data must be refetched, which it will do
+automatically. For this reason, it should never be necessary to clear the cache
+for any reason other than reclaiming disk space, thus why `clean` now requires
+`--force` to run.
+
+There is currently no method exposed through npm to inspect or directly manage
+the contents of this cache. In order to access it, `cacache` must be used
+directly.
+
+npm will not remove data by itself: the cache will grow as new packages are
+installed.
 
-* .../package/package.json:
-  The package.json file, as npm sees it.
-* .../package.tgz:
-  The tarball for that version.
+## A NOTE ABOUT THE CACHE'S DESIGN
 
-Additionally, whenever a registry request is made, a `.cache.json` file
-is placed at the corresponding URI, to store the ETag and the requested
-data.  This is stored in `{cache}/{hostname}/{path}/.cache.json`.
+The npm cache is strictly a cache: it should not be relied upon as a persistent
+and reliable data store for package data. npm makes no guarantee that a
+previously-cached piece of data will be available later, and will automatically
+delete corrupted contents. The primary guarantee that the cache makes is that,
+if it does return data, that data will be exactly the data that was inserted.
 
-Commands that make non-essential registry requests (such as `search` and
-`view`, or the completion scripts) generally specify a minimum timeout.
-If the `.cache.json` file is younger than the specified timeout, then
-they do not make an HTTP request to the registry.
+To run an offline verification of existing cache contents, use `npm cache
+verify`.
 
 ## CONFIGURATION
 
@@ -69,3 +79,5 @@ The root cache folder.
 * npm-install(1)
 * npm-publish(1)
 * npm-pack(1)
+* https://npm.im/cacache
+* https://npm.im/pacote
diff --git a/deps/npm/doc/cli/npm-install.md b/deps/npm/doc/cli/npm-install.md
index 6a37fcc76b..44cb68792b 100644
--- a/deps/npm/doc/cli/npm-install.md
+++ b/deps/npm/doc/cli/npm-install.md
@@ -8,18 +8,21 @@ npm-install(1) -- Install a package
     npm install [<@scope>/]<name>@<tag>
     npm install [<@scope>/]<name>@<version>
     npm install [<@scope>/]<name>@<version range>
+    npm install <git-host>:<git-user>/<repo-name>
+    npm install <git repo url>
     npm install <tarball file>
     npm install <tarball url>
     npm install <folder>
 
     alias: npm i
-    common options: [-S|--save|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--dry-run]
+    common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]
 
 ## DESCRIPTION
 
 This command installs a package, and any packages that it depends on. If the
-package has a shrinkwrap file, the installation of dependencies will be driven
-by that. See npm-shrinkwrap(1).
+package has a package-lock or shrinkwrap file, the installation of dependencies
+will be driven by that, with an `npm-shrinkwrap.json` taking precedence if both
+files exist. See package-lock.json(5) and npm-shrinkwrap(1).
 
 A `package` is:
 
@@ -54,13 +57,17 @@ after packing it up into a tarball (b).
 
 * `npm install <folder>`:
 
-    Install a package that is sitting in a folder on the filesystem.
+    Install the package in the directory as a symlink in the current project.
+    Its dependencies will be installed before it's linked. If `<folder>` sits
+    inside the root of your project, its dependencies may be hoisted to the
+    toplevel `node_modules` as they would for other types of dependencies.
 
 * `npm install <tarball file>`:
 
     Install a package that is sitting on the filesystem.  Note: if you just want
     to link a dev directory into your npm root, you can do this more easily by
-    using `npm link`.
+    using `npm link`. The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as
+    the extension.
 
     Example:
 
@@ -75,27 +82,31 @@ after packing it up into a tarball (b).
 
           npm install https://github.com/indexzero/forever/tarball/v0.5.6
 
-* `npm install [<@scope>/]<name> [-S|--save|-D|--save-dev|-O|--save-optional]`:
+* `npm install [<@scope>/]<name>`:
 
     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
     `npm-config(7)`. The config's default value is `latest`.)
 
-    In most cases, this will install the latest version
-    of the module published on npm.
+    In most cases, this will install the version of the modules tagged as
+    `latest` on the npm registry.
 
     Example:
 
           npm install sax
 
-    `npm install` takes 3 exclusive, optional flags which save or update
-    the package version in your main package.json:
+    `npm install` saves any specified packages into `dependencies` by default.
+    Additionally, you can control where and how they get saved with some
+    additional flags:
 
-    * `-S, --save`: Package will appear in your `dependencies`.
+    * `-P, --save-prod`: Package will appear in your `dependencies`. This is the
+                         default unless `-D` or `-O` are present.
 
     * `-D, --save-dev`: Package will appear in your `devDependencies`.
 
     * `-O, --save-optional`: Package will appear in your `optionalDependencies`.
 
+    * `--no-save`: Prevents saving to `dependencies`.
+
     When using any of the above options to save dependencies to your
     package.json, there are two additional, optional flags:
 
@@ -105,8 +116,8 @@ after packing it up into a tarball (b).
 
     * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
 
-    Further, if you have an `npm-shrinkwrap.json` then it will be updated as
-    well.
+    Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it
+    will be updated as well.
 
     `<scope>` is optional. The package will be downloaded from the registry
     associated with the specified scope. If no registry is associated with
@@ -118,13 +129,13 @@ after packing it up into a tarball (b).
 
     Examples:
 
-          npm install sax --save
+          npm install sax
           npm install githubname/reponame
           npm install @myorg/privatepackage
           npm install node-tap --save-dev
           npm install dtrace-provider --save-optional
-          npm install readable-stream --save --save-exact
-          npm install ansi-regex --save --save-bundle
+          npm install readable-stream --save-exact
+          npm install ansi-regex --save-bundle
 
 
     **Note**: If there is a file or folder named `<name>` in the current
@@ -167,20 +178,30 @@ after packing it up into a tarball (b).
 
 * `npm install <git remote url>`:
 
-    Installs the package from the hosted git provider, cloning it with
-    `git`. First it tries via the https (git with github) and if that fails, via ssh.
+    Installs the package from the hosted git provider, cloning it with `git`.
+    For a full git remote url, only that URL will be attempted.
+
+          <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
+
+    `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or
+    `git+file`.
 
-          <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish>]
+    If `#<commit-ish>` is provided, it will be used to clone exactly that
+    commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
+    be any valid semver range or exact version, and npm will look for any tags
+    or refs matching that range in the remote repository, much as it would for a
+    registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
+    specified, then `master` is used.
 
-    `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`,
-    or `git+file`.
-    If no `<commit-ish>` is specified, then `master` is used.
+    If the repository makes use of submodules, those submodules will be cloned
+    as well.
 
-    If the repository makes use of submodules, those submodules will
-    be cloned as well.
+    If the package being installed contains a `prepare` script, its
+    `dependencies` and `devDependencies` will be installed, and the prepare
+    script will be run, before the package is packaged and installed.
 
-    The following git environment variables are recognized by npm and will be added
-    to the environment when running git:
+    The following git environment variables are recognized by npm and will be
+    added to the environment when running git:
 
     * `GIT_ASKPASS`
     * `GIT_EXEC_PATH`
@@ -195,6 +216,7 @@ after packing it up into a tarball (b).
     Examples:
 
           npm install git+ssh://git@github.com:npm/npm.git#v1.0.27
+          npm install git+ssh://git@github.com:npm/npm#semver:^5.0
           npm install git+https://isaacs@github.com/npm/npm.git
           npm install git://github.com/npm/npm.git#v1.0.27
           GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/npm.git
@@ -205,20 +227,31 @@ after packing it up into a tarball (b).
     Install the package at `https://github.com/githubname/githubrepo` by
     attempting to clone it using `git`.
 
-    If you don't specify a *commit-ish* then `master` will be used.
+    If `#<commit-ish>` is provided, it will be used to clone exactly that
+    commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
+    be any valid semver range or exact version, and npm will look for any tags
+    or refs matching that range in the remote repository, much as it would for a
+    registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
+    specified, then `master` is used.
+
+    As with regular git dependencies, `dependencies` and `devDependencies` will
+    be installed if the package has a `prepare` script, before the package is
+    done installing.
 
     Examples:
 
           npm install mygithubuser/myproject
           npm install github:mygithubuser/myproject
 
-* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>]`:
+* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`:
 
     Install the package at `https://gist.github.com/gistID` by attempting to
     clone it using `git`. The GitHub username associated with the gist is
-    optional and will not be saved in `package.json` if `-S` or `--save` is used.
+    optional and will not be saved in `package.json`.
 
-    If you don't specify a *commit-ish* then `master` will be used.
+    As with regular git dependencies, `dependencies` and `devDependencies` will
+    be installed if the package has a `prepare` script, before the package is
+    done installing.
 
     Example:
 
@@ -229,7 +262,16 @@ after packing it up into a tarball (b).
     Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo`
     by attempting to clone it using `git`.
 
-    If you don't specify a *commit-ish* then `master` will be used.
+    If `#<commit-ish>` is provided, it will be used to clone exactly that
+    commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
+    be any valid semver range or exact version, and npm will look for any tags
+    or refs matching that range in the remote repository, much as it would for a
+    registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
+    specified, then `master` is used.
+
+    As with regular git dependencies, `dependencies` and `devDependencies` will
+    be installed if the package has a `prepare` script, before the package is
+    done installing.
 
     Example:
 
@@ -240,11 +282,21 @@ after packing it up into a tarball (b).
     Install the package at `https://gitlab.com/gitlabname/gitlabrepo`
     by attempting to clone it using `git`.
 
-    If you don't specify a *commit-ish* then `master` will be used.
+    If `#<commit-ish>` is provided, it will be used to clone exactly that
+    commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can
+    be any valid semver range or exact version, and npm will look for any tags
+    or refs matching that range in the remote repository, much as it would for a
+    registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is
+    specified, then `master` is used.
+
+    As with regular git dependencies, `dependencies` and `devDependencies` will
+    be installed if the package has a `prepare` script, before the package is
+    done installing.
 
     Example:
 
           npm install gitlab:mygitlabuser/myproject
+          npm install gitlab:myusr/myproj#semver:^5.0
 
 You may combine multiple arguments, and even multiple types of arguments.
 For example:
@@ -272,7 +324,7 @@ global `node_modules` folder. Only your direct dependencies will show in
 `node_modules` and everything they depend on will be flattened in their
 `node_modules` folders. This obviously will eliminate some deduping.
 
-The `--ignore-scripts` argument will cause npm to not execute any 
+The `--ignore-scripts` argument will cause npm to not execute any
 scripts defined in the package.json. See `npm-scripts(7)`.
 
 The `--legacy-bundling` argument will cause npm to install the package such
@@ -289,7 +341,7 @@ The `--no-optional` argument will prevent optional dependencies from
 being installed.
 
 The `--no-shrinkwrap` argument, which will ignore an available
-shrinkwrap file and use the package.json instead.
+package lock or shrinkwrap file and use the package.json instead.
 
 The `--nodedir=/path/to/node/source` argument will allow npm to find the
 node source code so that npm can compile native modules.
@@ -336,7 +388,9 @@ For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces:
     +-- D@1
 
 Because B's D@1 will be installed in the top level, C now has to install D@2
-privately for itself.
+privately for itself. This algorithm is deterministic, but different trees may
+be produced if two dependencies are requested for installation in a different
+order.
 
 See npm-folders(5) for a more detailed description of the specific
 folder structures that npm creates.
diff --git a/deps/npm/doc/cli/npm-publish.md b/deps/npm/doc/cli/npm-publish.md
index caf1fd2430..892786b61d 100644
--- a/deps/npm/doc/cli/npm-publish.md
+++ b/deps/npm/doc/cli/npm-publish.md
@@ -48,6 +48,10 @@ Once a package is published with a given name and version, that
 specific name and version combination can never be used again, even if
 it is removed with npm-unpublish(1).
 
+As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the
+tarball will be submitted to the registry during publication. Subsequent
+installs will use the strongest supported algorithm to verify downloads.
+
 For a "dry run" that does everything except actually publishing to the
 registry, see `npm-pack(1)`, which figures out the files to be included and
 packs them into a tarball to be uploaded to the registry.
diff --git a/deps/npm/doc/cli/npm-shrinkwrap.md b/deps/npm/doc/cli/npm-shrinkwrap.md
index ae04bd02bb..4c223a86cc 100644
--- a/deps/npm/doc/cli/npm-shrinkwrap.md
+++ b/deps/npm/doc/cli/npm-shrinkwrap.md
@@ -1,4 +1,4 @@
-npm-shrinkwrap(1) -- Lock down dependency versions
+npm-shrinkwrap(1) -- Lock down dependency versions for publication
 =====================================================
 
 ## SYNOPSIS
@@ -7,181 +7,11 @@ npm-shrinkwrap(1) -- Lock down dependency versions
 
 ## DESCRIPTION
 
-This command locks down the versions of a package's dependencies so
-that you can control exactly which versions of each dependency will be
-used when your package is installed. The `package.json` file is still
-required if you want to use `npm install`.
-
-By default, `npm install` recursively installs the target's
-dependencies (as specified in `package.json`), choosing the latest
-available version that satisfies the dependency's semver pattern. In
-some situations, particularly when shipping software where each change
-is tightly managed, it's desirable to fully specify each version of
-each dependency recursively so that subsequent builds and deploys do
-not inadvertently pick up newer versions of a dependency that satisfy
-the semver pattern. Specifying specific semver patterns in each
-dependency's `package.json` would facilitate this, but that's not always
-possible or desirable, as when another author owns the npm package.
-It's also possible to check dependencies directly into source control,
-but that may be undesirable for other reasons.
-
-As an example, consider package A:
-
-    {
-      "name": "A",
-      "version": "0.1.0",
-      "dependencies": {
-        "B": "<0.1.0"
-      }
-    }
-
-package B:
-
-    {
-      "name": "B",
-      "version": "0.0.1",
-      "dependencies": {
-        "C": "<0.1.0"
-      }
-    }
-
-and package C:
-
-    {
-      "name": "C",
-      "version": "0.0.1"
-    }
-
-If these are the only versions of A, B, and C available in the
-registry, then a normal `npm install A` will install:
-
-    A@0.1.0
-    `-- B@0.0.1
-        `-- C@0.0.1
-
-However, if B@0.0.2 is published, then a fresh `npm install A` will
-install:
-
-    A@0.1.0
-    `-- B@0.0.2
-        `-- C@0.0.1
-
-assuming the new version did not modify B's dependencies. Of course,
-the new version of B could include a new version of C and any number
-of new dependencies. If such changes are undesirable, the author of A
-could specify a dependency on B@0.0.1. However, if A's author and B's
-author are not the same person, there's no way for A's author to say
-that he or she does not want to pull in newly published versions of C
-when B hasn't changed at all.
-
-In this case, A's author can run
-
-    npm shrinkwrap
-
-This generates `npm-shrinkwrap.json`, which will look something like this:
-
-    {
-      "name": "A",
-      "version": "0.1.0",
-      "dependencies": {
-        "B": {
-          "version": "0.0.1",
-          "from": "B@^0.0.1",
-          "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
-          "dependencies": {
-            "C": {
-              "version": "0.0.1",
-              "from": "org/C#v0.0.1",
-              "resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
-            }
-          }
-        }
-      }
-    }
-
-The shrinkwrap command has locked down the dependencies based on what's
-currently installed in `node_modules`.  The installation behavior is changed to:
-
-1. The module tree described by the shrinkwrap is reproduced. This means
-reproducing the structure described in the file, using the specific files
-referenced in "resolved" if available, falling back to normal package
-resolution using "version" if one isn't.
-
-2. The tree is walked and any missing dependencies are installed in the usual fashion.
-
-If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts` property of the
-`package.json`, they will be executed by running `npm shrinkwrap`.
-`preshrinkwrap` and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
-executed afterwards. For example to run some postprocessing on the generated file:
-
-    "scripts": { "postshrinkwrap": "node fix-shrinkwrap.js" }
-
-
-### Using shrinkwrapped packages
-
-Using a shrinkwrapped package is no different than using any other
-package: you can `npm install` it by hand, or add a dependency to your
-`package.json` file and `npm install` it.
-
-### Building shrinkwrapped packages
-
-To shrinkwrap an existing package:
-
-1. Run `npm install` in the package root to install the current
-   versions of all dependencies.
-2. Validate that the package works as expected with these versions.
-3. Run `npm shrinkwrap`, add `npm-shrinkwrap.json` to git, and publish
-   your package.
-
-To add or update a dependency in a shrinkwrapped package:
-
-1. Run `npm install` in the package root to install the current
-   versions of all dependencies.
-2. Add or update dependencies. `npm install --save` or `npm install --save-dev`
-   each new or updated package individually to update the `package.json` and
-   the shrinkwrap. Note that they must be explicitly named in order to be
-   installed: running `npm install` with no arguments will merely reproduce
-   the existing shrinkwrap.
-3. Validate that the package works as expected with the new
-   dependencies.
-4. Commit the new `npm-shrinkwrap.json`, and publish your package.
-
-You can use npm-outdated(1) to view dependencies with newer versions
-available.
-
-### Other Notes
-
-A shrinkwrap file must be consistent with the package's `package.json`
-file. `npm shrinkwrap` will fail if required dependencies are not
-already installed, since that would result in a shrinkwrap that
-wouldn't actually work. Similarly, the command will fail if there are
-extraneous packages (not referenced by `package.json`), since that would
-indicate that `package.json` is not correct.
-
-Starting with npm v4.0.1, `devDependencies` are included when you run
-`npm shrinkwrap` and follow the usual rules as to when they're installed.
-As of npm v3.10.8, if you run `npm install --only=production` or
-`npm install --production` with a shrinkwrap including your development
-dependencies they won't be installed. Similarly, if the environment
-variable `NODE_ENV` is `production` then they won't be installed. If you
-need compatibility with versions of npm prior to v3.10.8 or otherwise
-don't want them in your shrinkwrap you can exclude development
-dependencies with:
-`npm shrinkwrap --only=prod` or `npm shrinkwrap --production`.
-
-If shrinkwrapped package A depends on shrinkwrapped package B, B's
-shrinkwrap will not be used as part of the installation of A. However,
-because A's shrinkwrap is constructed from a valid installation of B
-and recursively specifies all dependencies, the contents of B's
-shrinkwrap will implicitly be included in A's shrinkwrap.
-
-### Caveats
-
-If you wish to lock down the specific bytes included in a package, for
-example to have 100% confidence in being able to reproduce a
-deployment or build, then you ought to check your dependencies into
-source control, or pursue some other mechanism that can verify
-contents rather than versions.
+This command repurposes `package-lock.json` into a publishable
+`npm-shrinkwrap.json` or simply creates a new one. The file created and updated
+by this command will then take precedence over any other existing or future
+`package-lock.json` files. For a detailed explanation of the design and purpose
+of package locks in npm, see npm-package-locks(5).
 
 ## SEE ALSO
 
@@ -189,4 +19,7 @@ contents rather than versions.
 * npm-run-script(1)
 * npm-scripts(7)
 * package.json(5)
+* npm-package-locks(5)
+* package-lock.json(5)
+* npm-shrinkwrap.json(5)
 * npm-ls(1)
diff --git a/deps/npm/doc/files/npm-package-locks.md b/deps/npm/doc/files/npm-package-locks.md
new file mode 100644
index 0000000000..73786dc91a
--- /dev/null
+++ b/deps/npm/doc/files/npm-package-locks.md
@@ -0,0 +1,145 @@
+npm-package-locks(5) -- An explanation of npm lockfiles
+=====================================================
+
+## DESCRIPTION
+
+Conceptually, the "input" to npm-install(1) is a package.json(5), while its
+"output" is a fully-formed `node_modules` tree: a representation of the
+dependencies you declared. In an ideal world, npm would work like a pure
+function: the same `package.json` should produce the exact same `node_modules`
+tree, any time. In some cases, this is indeed true. But in many others, npm is
+unable to do this. There are multiple reasons for this:
+
+* different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
+
+* a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
+
+* A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`)
+
+* The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
+
+As an example, consider package A:
+
+    {
+      "name": "A",
+      "version": "0.1.0",
+      "dependencies": {
+        "B": "<0.1.0"
+      }
+    }
+
+package B:
+
+    {
+      "name": "B",
+      "version": "0.0.1",
+      "dependencies": {
+        "C": "<0.1.0"
+      }
+    }
+
+and package C:
+
+    {
+      "name": "C",
+      "version": "0.0.1"
+    }
+
+If these are the only versions of A, B, and C available in the
+registry, then a normal `npm install A` will install:
+
+    A@0.1.0
+    `-- B@0.0.1
+        `-- C@0.0.1
+
+However, if B@0.0.2 is published, then a fresh `npm install A` will
+install:
+
+    A@0.1.0
+    `-- B@0.0.2
+        `-- C@0.0.1
+
+assuming the new version did not modify B's dependencies. Of course,
+the new version of B could include a new version of C and any number
+of new dependencies. If such changes are undesirable, the author of A
+could specify a dependency on B@0.0.1. However, if A's author and B's
+author are not the same person, there's no way for A's author to say
+that he or she does not want to pull in newly published versions of C
+when B hasn't changed at all.
+
+To prevent this potential issue, npm uses package-lock.json(5) or, if present,
+npm-shrinkwrap.json(5). These files are called package locks, or lockfiles.
+
+Whenever you run `npm install`, npm generates or updates your package lock,
+which will look something like this:
+
+    {
+      "name": "A",
+      "version": "0.1.0",
+      ...metadata fields...
+      "dependencies": {
+        "B": {
+          "version": "0.0.1",
+          "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
+          "integrity": "sha512-DeAdb33F+"
+          "dependencies": {
+            "C": {
+              "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
+            }
+          }
+        }
+      }
+    }
+
+This file describes an *exact*, and more importantly *reproducible*
+`node_modules` tree. Once it's present, and future installation will base its
+work off this file, instead of recalculating dependency versions off
+package.json(5).
+
+The presence of a package lock changes the installation behavior such that:
+
+1. The module tree described by the package lock is reproduced. This means
+reproducing the structure described in the file, using the specific files
+referenced in "resolved" if available, falling back to normal package resolution
+using "version" if one isn't.
+
+2. The tree is walked and any missing dependencies are installed in the usual
+fashion.
+
+If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts`
+property of the `package.json`, they will be executed in order. `preshrinkwrap`
+and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
+executed afterwards. These scripts run for both `package-lock.json` and
+`npm-shrinkwrap.json`. For example to run some postprocessing on the generated
+file:
+
+    "scripts": {
+      "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
+    }
+
+
+### Using locked packages
+
+Using a locked package is no different than using any package without a package
+lock: any commands that update `node_modules` and/or `package.json`'s
+dependencies will automatically sync the existing lockfile. This includes `npm
+install`, `npm rm`, `npm update`, etc. To prevent this update from happening,
+you can use the `--no-save` option to prevent saving altogether, or
+`--no-shrinkwrap` to allow `package.json` to be updated while leaving
+`package-lock.json` or `npm-shrinkwrap.json` intact.
+
+It is highly recommended you commit the generated package lock to source
+control: this will allow anyone else on your team, your deployments, your
+CI/continuous integration, and anyone else who runs `npm install` in your
+package source to get the exact same dependency tree that you were developing
+on. Additionally, the diffs from these changes are human-readable and will
+inform you of any changes npm has made to your `node_modules`, so you can notice
+if any transitive dependencies were updated, hoisted, etc.
+
+## SEE ALSO
+
+* https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
+* package.json(5)
+* package-lock.json(5)
+* npm-shrinkwrap.json(5)
+* npm-shrinkwrap(1)
diff --git a/deps/npm/doc/files/npm-shrinkwrap.json.md b/deps/npm/doc/files/npm-shrinkwrap.json.md
new file mode 100644
index 0000000000..8256398e86
--- /dev/null
+++ b/deps/npm/doc/files/npm-shrinkwrap.json.md
@@ -0,0 +1,27 @@
+npm-shrinkwrap.json(5) -- A publishable lockfile
+=====================================================
+
+## DESCRIPTION
+
+`npm-shrinkwrap.json` is a file created by npm-shrinkwrap(1). It is identical to
+`package-lock.json`, with one major caveat: Unlike `package-lock.json`,
+`npm-shrinwkrap.json` may be included when publishing a package.
+
+The recommended use-case for `npm-shrinkwrap.json` is applications deployed
+through the publishing process on the registry: for example, daemons and
+command-line tools intended as global installs or `devDependencies`. It's
+strongly discouraged for library authors to publish this file, since that would
+prevent end users from having control over transitive dependency updates.
+
+Additionally, if both `package-lock.json` and `npm-shrinwkrap.json` are present
+in a package root, `package-lock.json` will be ignored in favor of this file.
+
+For full details and description of the `npm-shrinkwrap.json` file format, refer
+to the manual page for package-lock.json(5).
+
+## SEE ALSO
+
+* npm-shrinkwrap(1)
+* package-lock.json(5)
+* package.json(5)
+* npm-install(1)
diff --git a/deps/npm/doc/files/package-lock.json.md b/deps/npm/doc/files/package-lock.json.md
new file mode 100644
index 0000000000..dad219b4a1
--- /dev/null
+++ b/deps/npm/doc/files/package-lock.json.md
@@ -0,0 +1,132 @@
+package-lock.json(5) -- A manifestation of the manifest
+=====================================================
+
+## DESCRIPTION
+
+`package-lock.json` is automatically generated for any operations where npm
+modifies either the `node_modules` tree, or `package.json`. It describes the
+exact tree that was generated, such that subsequent installs are able to
+generate identical trees, regardless of intermediate dependency updates.
+
+This file is intended to be committed into source repositories, and serves
+various purposes:
+
+* Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
+
+* Provide a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself.
+
+* To facilitate greater visibility of tree changes through readable source control diffs.
+
+* And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.
+
+One key detail about `package-lock.json` is that it cannot be published, and it
+will be ignored if found in any place other than the toplevel package. It shares
+a format with npm-shrinkwrap.json(5), which is essentially the same file, but
+allows publication. This is not recommended unless deploying a CLI tool or
+otherwise using the publication process for producing production packages.
+
+If both `package-lock.json` and `npm-shrinkwrap.json` are present in the root of
+a package, `package-lock.json` will be completely ignored.
+
+
+## FILE FORMAT
+
+### name
+
+The name of the package this is a package-lock for. This must match what's in
+`package.json`.
+
+### version
+
+The version of the package this is a package-lock for. This must match what's in
+`package.json`.
+
+### lockfileVersion
+
+An integer version, starting at `1` with the version number of this document
+whose semantics were used when generating this `package-lock.json`.
+
+### packageIntegrity
+
+This is a [subresource
+integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) value
+created from the `pacakge.json`. No preprocessing of the `package.json` should
+be done. Subresource integrity strings can be produced by modules like
+[`ssri`](https://www.npmjs.com/package/ssri).
+
+### preserveSymlinks
+
+Indicates that the install was done with the environment variable
+`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of
+this property match that environment variable.
+
+### dependencies
+
+A mapping of package name to dependency object.  Dependency objects have the
+following properties:
+
+#### version
+
+This is a specifier that uniquely identifies this package and should be
+usable in fetching a new copy of it.
+
+* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
+* registry sources: This is a version number. (eg, `1.2.3`)
+* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
+* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
+* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
+* local link sources: This is the file URL of the link. (eg `file:libs/our-module`)
+
+#### integrity
+
+This is a [Standard Subresource
+Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for this
+resource.
+
+* For bundled dependencies this is not included, regardless of source.
+* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
+* For git sources this is the specific commit hash we cloned from.
+* For remote tarball sources this is an integrity based on a SHA512 of
+  the file.
+* For local tarball sources: This is an integrity field based on the SHA512 of the file.
+
+#### resolved
+
+* For bundled dependencies this is not included, regardless of source.
+* For registry sources this is path of the tarball relative to the registry
+  URL.  If the tarball URL isn't on the same server as the registry URL then
+  this is a complete URL.
+
+#### bundled
+
+If true, this is the bundled dependency and will be installed by the parent
+module.  When installing, this module will be extracted from the parent
+module during the extract phase, not installed as a separate dependency.
+
+#### dev
+
+If true then this dependency is either a development dependency ONLY of the
+top level module or a transitive dependency of one.  This is false for
+dependencies that are both a development dependency of the top level and a
+transitive dependency of a non-development dependency of the top level.
+
+#### optional
+
+If true then this dependency is either an optional dependency ONLY of the
+top level module or a transitive dependency of one.  This is false for
+dependencies that are both an optional dependency of the top level and a
+transitive dependency of a non-optional dependency of the top level.
+
+All optional dependencies should be included even if they're uninstallable
+on the current platform.
+
+#### dependencies
+
+The dependencies of this dependency, exactly as at the top level.
+
+## SEE ALSO
+
+* npm-shrinkwrap(1)
+* package-lock.json(5)
+* package.json(5)
+* npm-install(1)
diff --git a/deps/npm/doc/misc/npm-config.md b/deps/npm/doc/misc/npm-config.md
index 0b7db2e0e5..6fee98a90c 100644
--- a/deps/npm/doc/misc/npm-config.md
+++ b/deps/npm/doc/misc/npm-config.md
@@ -63,6 +63,7 @@ The following shorthands are parsed on the command-line:
 * `-f`: `--force`
 * `-desc`: `--description`
 * `-S`: `--save`
+* `-P`: `--save-prod`
 * `-D`: `--save-dev`
 * `-O`: `--save-optional`
 * `-B`: `--save-bundle`
@@ -682,6 +683,16 @@ Attempt to install packages in the `optionalDependencies` object.  Note
 that if these packages fail to install, the overall installation
 process is not aborted.
 
+### package-lock
+
+* Default: true
+* Type: Boolean
+
+If set to false, then ignore `package-lock.json` files when installing. This
+will also prevent _writing_ `package-lock.json` if `save` is true.
+
+This option is an alias for `--shrinkwrap`.
+
 ### parseable
 
 * Default: false
@@ -803,6 +814,17 @@ If a package would be saved at install time by the use of `--save`,
 When used with the `npm rm` command, it removes it from the
 bundledDependencies list.
 
+### save-prod
+
+* Default: false
+* Type: Boolean
+
+Makes sure that a package will be saved into `dependencies` specifically. This
+is useful if a package already exists in `devDependencies` or
+`optionalDependencies`, but you want to move it to be a production dep. This is
+also the default behavior if `--save` is true, and neither `--save-dev` or
+`--save-optional` are true.
+
 ### save-dev
 
 * Default: false
@@ -934,8 +956,10 @@ The shell to run for the `npm explore` command.
 * Default: true
 * Type: Boolean
 
-If set to false, then ignore `npm-shrinkwrap.json` files when
-installing.
+If set to false, then ignore `npm-shrinkwrap.json` files when installing. This
+will also prevent _writing_ `npm-shrinkwrap.json` if `save` is true.
+
+This option is an alias for `--package-lock`.
 
 ### sign-git-tag
 
diff --git a/deps/npm/doc/misc/npm-index.md b/deps/npm/doc/misc/npm-index.md
index 7569a225c7..ed478d84ad 100644
--- a/deps/npm/doc/misc/npm-index.md
+++ b/deps/npm/doc/misc/npm-index.md
@@ -163,7 +163,7 @@ Search for packages
 
 ### npm-shrinkwrap(1)
 
-Lock down dependency versions
+Lock down dependency versions for publication
 
 ### npm-star(1)
 
@@ -225,10 +225,22 @@ File system structures npm uses
 
 Folder Structures Used by npm
 
+### npm-package-locks(5)
+
+An explanation of npm lockfiles
+
+### npm-shrinkwrap.json(5)
+
+A publishable lockfile
+
 ### npmrc(5)
 
 The npm config files
 
+### package-lock.json(5)
+
+A manifestation of the manifest
+
 ### package.json(5)
 
 Specifics of npm's package.json handling
diff --git a/deps/npm/doc/misc/npm-scripts.md b/deps/npm/doc/misc/npm-scripts.md
index 3f048716de..0e9c3bc6e7 100644
--- a/deps/npm/doc/misc/npm-scripts.md
+++ b/deps/npm/doc/misc/npm-scripts.md
@@ -7,14 +7,20 @@ npm supports the "scripts" property of the package.json script, for the
 following scripts:
 
 * prepublish:
-  Run BEFORE the package is published.  (Also run on local `npm
-  install` without any arguments. See below.)
+  Run BEFORE the package is packed and published, as well as on local `npm
+  install` without any arguments. (See below)
 * prepare:
-  Run both BEFORE the package is published, and on local `npm
-  install` without any arguments. (See below.) This is run
+  Run both BEFORE the package is packed and published, and on local `npm
+  install` without any arguments (See below). This is run
   AFTER `prepublish`, but BEFORE `prepublishOnly`.
 * prepublishOnly:
-  Run BEFORE the package is published. (See below.)
+  Run BEFORE the package is prepared and packed, ONLY on `npm publish`. (See
+  below.)
+* prepack:
+  run BEFORE a tarball is packed (on `npm pack`, `npm publish`, and when
+  installing git dependencies)
+* postpack:
+  Run AFTER the tarball has been generated and moved to its final destination.
 * publish, postpublish:
   Run AFTER the package is published.
 * preinstall: