deps: upgrade npm to 10.5.0

PR-URL: #51913
Reviewed-By: Marco Ippolito <[email protected]>
Reviewed-By: Richard Lau <[email protected]>

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

@@ -374,7 +374,8 @@ the order in which omit/include are specified on the command-line.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -169,7 +169,8 @@ this warning is treated as a failure.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -44,7 +44,8 @@ npm config set key=value [key=value...]
 npm set key=value [key=value...]
 ```
 
-Sets each of the config keys to the value provided.
+Sets each of the config keys to the value provided. Modifies the user configuration
+file unless [`location`](/commands/npm-config#location) is passed.
 
 If value is omitted, the key will be removed from your config file entirely.
 

deps/npm/docs/content/commands/npm-install-ci-test.md

@@ -115,7 +115,8 @@ this warning is treated as a failure.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

deps/npm/docs/content/commands/npm-install-test.md

@@ -192,7 +192,8 @@ For `list` this means the output will be based on the tree described by the
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -582,7 +582,8 @@ For `list` this means the output will be based on the tree described by the
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -27,7 +27,7 @@ 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@10.3.0 /path/to/npm
+npm@10.5.0 /path/to/npm
 └─┬ [email protected]
   └── [email protected]
 ```

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

@@ -99,7 +99,8 @@ Not supported by all npm commands.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -135,19 +135,32 @@ npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
   },
   ...
 ```
-### Package lock only mode
 
-If package-lock-only is enabled, only the information in the package
-lock (or shrinkwrap) is loaded.  This means that information from the
-package.json files of your dependencies will not be included in the
-result set (e.g. description, homepage, engines).
+### Expecting a certain number of results
+
+One common use of `npm query` is to make sure there is only one version of
+a certain dependency in your tree.  This is especially common for
+ecosystems like that rely on `typescript` where having state split
+across two different but identically-named packages causes bugs.  You
+can use the `--expect-results` or `--expect-result-count` in your setup
+to ensure that npm will exit with an exit code if your tree doesn't look
+like you want it to.
+
+
+```sh
+$ npm query '#react' --expect-result-count=1
+```
+
+Perhaps you want to quickly check if there are any production
+dependencies that could be updated:
+
+```sh
+$ npm query ':root>:outdated(in-range).prod' --no-expect-results
+```
 
 ### Package lock only mode
 
-If package-lock-only is enabled, only the information in the package
-lock (or shrinkwrap) is loaded.  This means that information from the
-package.json files of your dependencies will not be included in the
-result set (e.g. description, homepage, engines).
+If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.  This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
 
 ### Configuration
 
@@ -235,6 +248,25 @@ For `list` this means the output will be based on the tree described by the
 `package-lock.json`, rather than the contents of `node_modules`.
 
 
+
+#### `expect-results`
+
+* Default: null
+* Type: null or Boolean
+
+Tells npm whether or not to expect results from the command. Can be either
+true (expect some results) or false (expect no results).
+
+This config can not be used with: `expect-result-count`
+
+#### `expect-result-count`
+
+* Default: null
+* Type: null or Number
+
+Tells to expect a specific number of results from the command.
+
+This config can not be used with: `expect-results`
 ## See Also
 
 * [dependency selectors](/using-npm/dependency-selectors)

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

@@ -72,7 +72,8 @@ systems.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

deps/npm/docs/content/commands/npm-run-script.md

@@ -220,7 +220,8 @@ will *not* run any pre- or post-scripts.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -28,7 +28,7 @@ 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
+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).
@@ -80,7 +80,7 @@ However, if `app`'s `package.json` contains:
 ```
 
 In this case, running `npm update` will install `[email protected]`.  Even though the
-`latest` tag points to `1.2.2`, this version do not satisfy `~1.1.1`, which is
+`latest` tag points to `1.2.2`, this version does not satisfy `~1.1.1`, which is
 equivalent to `>=1.1.1 <1.2.0`.  So the highest-sorting version that satisfies
 `~1.1.1` is used, which is `1.1.2`.
 
@@ -94,8 +94,7 @@ Suppose `app` has a caret dependency on a version below `1.0.0`, for example:
 }
 ```
 
-`npm update` will install `[email protected]`, because there are no other
-versions which satisfy `^0.2.0`.
+`npm update` will install `[email protected]`.
 
 If the dependence were on `^0.4.0`:
 
@@ -294,7 +293,8 @@ will also prevent _writing_ `package-lock.json` if `save` is true.
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

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

@@ -14,7 +14,7 @@ Note: This command is unaware of workspaces.
 
 ### Version
 
-10.3.0
+10.5.0
 
 ### Description
 

deps/npm/docs/content/configuring-npm/package-json.md

@@ -726,7 +726,7 @@ in which case they will be normalized to a relative path and added to your
 
 This feature is helpful for local offline development and creating tests
 that require npm installing where you don't want to hit an external server,
-but should not be used when publishing packages to the public registry.
+but should not be used when publishing your package to the public registry.
 
 *note*: Packages linked by local path will not have their own
 dependencies installed when `npm install` is ran in this case.  You must

deps/npm/docs/content/using-npm/config.md

@@ -6,6 +6,9 @@ description: More than you probably want to know about npm configuration
 
 ### Description
 
+This article details npm configuration in general. To learn about the `config` command,
+see [`npm config`](/commands/npm-config).
+
 npm gets its configuration values from the following sources, sorted by priority:
 
 #### Command Line Flags
@@ -489,6 +492,25 @@ This can be overridden by setting the `--force` flag.
 
 
 
+#### `expect-result-count`
+
+* Default: null
+* Type: null or Number
+
+Tells to expect a specific number of results from the command.
+
+This config can not be used with: `expect-results`
+
+#### `expect-results`
+
+* Default: null
+* Type: null or Boolean
+
+Tells npm whether or not to expect results from the command. Can be either
+true (expect some results) or false (expect no results).
+
+This config can not be used with: `expect-result-count`
+
 #### `fetch-retries`
 
 * Default: 2
@@ -570,7 +592,8 @@ recommended that you do not use this option!
 
 #### `foreground-scripts`
 
-* Default: false
+* Default: `false` unless when using `npm pack` or `npm publish` where it
+  defaults to `true`
 * Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

deps/npm/docs/content/using-npm/dependency-selectors.md

@@ -13,7 +13,7 @@ The [`npm query`](/commands/npm-query) command exposes a new dependency selector
 - Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
 - Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
 
-### Dependency Selector Syntax `v1.0.0`
+### Dependency Selector Syntax
 
 #### Overview:
 
@@ -62,6 +62,7 @@ The [`npm query`](/commands/npm-query) command exposes a new dependency selector
 - `:path(<path>)` [glob](https://www.npmjs.com/package/glob) matching based on dependencies path relative to the project
 - `:type(<type>)` [based on currently recognized types](https://github.com/npm/npm-package-arg#result-object)
 - `:outdated(<type>)` when a dependency is outdated
+- `:vuln(<selector>)` when a dependency has a known vulnerability
 
 ##### `:semver(<spec>, [selector], [function])`
 
@@ -84,8 +85,8 @@ Some examples:
 The `:outdated` pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated. The type parameter may be one of the following:
 
 - `any` (default) a version exists that is greater than the current one
-- `in-range` a version exists that is greater than the current one, and satisfies at least one if its dependents
-- `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its dependents
+- `in-range` a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies
+- `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its parent's dependencies
 - `major` a version exists that is a semver major greater than the current one
 - `minor` a version exists that is a semver minor greater than the current one
 - `patch` a version exists that is a semver patch greater than the current one
@@ -99,14 +100,29 @@ In addition to the filtering performed by the pseudo selector, some extra data i
 Some examples:
 
 - `:root > :outdated(major)` returns every direct dependency that has a new semver major release
-- `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its edges in
+- `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its parent's dependencies
+
+##### `:vuln`
+
+The `:vuln` pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability.  Only dependencies whose current version matches a vulnerability will be returned.  For example if you have `[email protected]` in your tree, a vulnerability for `semver` which affects versions `<=6.3.1` will not match.
+
+You can also filter results by certain attributes in advisories.  Currently that includes `severity` and `cwe`.  Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
+
+In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the `queryContext` attribute of each node under the `advisories` attribute.
+
+Some examples:
+
+- `:root > .prod:vuln` returns direct production dependencies with any known vulnerability
+- `:vuln([severity=high])` returns only dependencies with a vulnerability with a `high` severity.
+- `:vuln([severity=high],[severity=moderate])` returns only dependencies with a vulnerability with a `high`  or `moderate` severity.
+- `:vuln([cwe=1333])` returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)
 
 #### [Attribute Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
 
 The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
 
 - `[]` attribute selector (ie. existence of attribute)
-- `[attribute=value]` attribute value is equivalant...
+- `[attribute=value]` attribute value is equivalent...
 - `[attribute~=value]` attribute value contains word...
 - `[attribute*=value]` attribute value contains string...
 - `[attribute|=value]` attribute value is equal to or starts with...

deps/npm/docs/content/using-npm/scope.md

@@ -127,7 +127,7 @@ host multiple scopes, but a scope only ever points to one registry.
 You can also associate a scope with a registry using `npm config`:
 
 ```bash
-npm config set @myco:registry http://reg.example.com
+npm config set @myco:registry=http://reg.example.com
 ```
 
 Once a scope is associated with a registry, any `npm install` for a package

deps/npm/docs/content/using-npm/scripts.md

@@ -294,18 +294,15 @@ For example, if your package.json contains this:
 {
   "scripts" : {
     "install" : "scripts/install.js",
-    "postinstall" : "scripts/install.js",
-    "uninstall" : "scripts/uninstall.js"
+    "postinstall" : "scripts/install.js"
   }
 }
 ```
 
-then `scripts/install.js` will be called for the install
-and post-install stages of the lifecycle, and `scripts/uninstall.js`
-will be called when the package is uninstalled.  Since
-`scripts/install.js` is running for two different phases, it would
-be wise in this case to look at the `npm_lifecycle_event` environment
-variable.
+then `scripts/install.js` will be called for the install and post-install
+stages of the lifecycle.  Since `scripts/install.js` is running for two
+different phases, it would be wise in this case to look at the
+`npm_lifecycle_event` environment variable.
 
 If you want to run a make command, you can do so.  This works just
 fine:
@@ -334,10 +331,8 @@ file.
 ### Best Practices
 
 * Don't exit with a non-zero error code unless you *really* mean it.
-  Except for uninstall scripts, this will cause the npm action to
-  fail, and potentially be rolled back.  If the failure is minor or
-  only will prevent some optional features, then it's better to just
-  print a warning and exit successfully.
+  If the failure is minor or only will prevent some optional features, then
+  it's better to just print a warning and exit successfully.
 * Try not to use scripts to do what npm can do for you.  Read through
   [`package.json`](/configuring-npm/package-json) to see all the things that you can specify and enable
   by simply describing your package appropriately.  In general, this

deps/npm/docs/content/using-npm/workspaces.md

@@ -7,12 +7,12 @@ description: Working with workspaces
 ### Description
 
 **Workspaces** is a generic term that refers to the set of features in the
-npm cli that provides support to managing multiple packages from your local
+npm cli that provides support for managing multiple packages from your local
 file system from within a singular top-level, root package.
 
 This set of features makes up for a much more streamlined workflow handling
-linked packages from the local file system. Automating the linking process
-as part of `npm install` and avoiding manually having to use `npm link` in
+linked packages from the local file system. It automates the linking process
+as part of `npm install` and removes the need to manually use `npm link` in
 order to add references to packages that should be symlinked into the current
 `node_modules` folder.
 
@@ -110,7 +110,7 @@ respect the provided `workspace` configuration.
 
 ### Using workspaces
 
-Given the [specifities of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace
+Given the [specifics of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace
 by its declared `package.json` `name`. Continuing from the example defined
 above, let's also create a Node.js script that will require the workspace `a`
 example module, e.g: