<p>The <ahref="../commands/npm-query.html"><code>npm query</code></a> command exposes a new dependency selector syntax (informed by & respecting many aspects of the <ahref="https://dev.w3.org/csswg/selectors4/#relational">CSS Selectors 4 Spec</a>) which:</p>
<li>there is no "type" or "tag" selectors (ex. <code>div, h1, a</code>) as a dependency/target is the only type of <code>Node</code> that can be queried</li>
<li>the term "dependencies" is in reference to any <code>Node</code> found in a <code>tree</code> returned by <code>Arborist</code></li>
</ul>
<h4id="combinators">Combinators</h4>
<ul>
<li><code>></code> direct descendant/child</li>
<li><code></code> any descendant/child</li>
<li><code>~</code> sibling</li>
</ul>
<h4id="selectors">Selectors</h4>
<ul>
<li><code>*</code> universal selector</li>
<li><code>#<name></code> dependency selector (equivalent to <code>[name="..."]</code>)</li>
<li><code>#<name>@<version></code> (equivalent to <code>[name=<name>]:semver(<version>)</code>)</li>
<li><code>,</code> selector list delimiter</li>
<li><code>.</code> dependency type selector</li>
<li><code>:</code> pseudo selector</li>
</ul>
<h4id="dependency-type-selectors">Dependency Type Selectors</h4>
<ul>
<li><code>.prod</code> dependency found in the <code>dependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
<li><code>.dev</code> dependency found in the <code>devDependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
<li><code>.optional</code> dependency found in the <code>optionalDependencies</code> section of <code>package.json</code>, or has <code>"optional": true</code> set in its entry in the <code>peerDependenciesMeta</code> section of <code>package.json</code>, or a child of said dependency</li>
<li><code>.peer</code> dependency found in the <code>peerDependencies</code> section of <code>package.json</code></li>
<li><code>.workspace</code> dependency found in the <ahref="https://docs.npmjs.com/cli/v8/using-npm/workspaces"><code>workspaces</code></a> section of <code>package.json</code></li>
<li><code>.bundled</code> dependency found in the <code>bundleDependencies</code> section of <code>package.json</code>, or is a child of said dependency</li>
<li><ahref="https://developer.mozilla.org/en-US/docs/Web/CSS/:root"><code>:root</code></a> matches the root node/dependency</li>
<li><ahref="https://developer.mozilla.org/en-US/docs/Web/CSS/:scope"><code>:scope</code></a> matches node/dependency it was queried against</li>
<li><ahref="https://developer.mozilla.org/en-US/docs/Web/CSS/:empty"><code>:empty</code></a> when a dependency has no dependencies</li>
<li><ahref="https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private"><code>:private</code></a> when a dependency is private</li>
<li><code>:link</code> when a dependency is linked (for instance, workspaces or packages manually <ahref="https://docs.npmjs.com/cli/v8/commands/npm-link"><code>linked</code></a></li>
<li><code>:deduped</code> when a dependency has been deduped (note that this does <em>not</em> always mean the dependency has been hoisted to the root of node_modules)</li>
<li><code>:semver(<spec>, [selector], [function])</code> match a valid <ahref="https://github.com/npm/node-semver"><code>node-semver</code></a> version or range to a selector</li>
<li><code>:path(<path>)</code><ahref="https://www.npmjs.com/package/glob">glob</a> matching based on dependencies path relative to the project</li>
<li><code>:type(<type>)</code><ahref="https://github.com/npm/npm-package-arg#result-object">based on currently recognized types</a></li>
<p>The <code>:semver()</code> pseudo selector allows comparing fields from each node's <code>package.json</code> using <ahref="https://github.com/npm/node-semver#readme">semver</a> methods. It accepts up to 3 parameters, all but the first of which are optional.</p>
<ul>
<li><code>spec</code> a semver version or range</li>
<li><code>selector</code> an attribute selector for each node (default <code>[version]</code>)</li>
<li><code>function</code> a semver method to apply, one of: <code>satisfies</code>, <code>intersects</code>, <code>subset</code>, <code>gt</code>, <code>gte</code>, <code>gtr</code>, <code>lt</code>, <code>lte</code>, <code>ltr</code>, <code>eq</code>, <code>neq</code> or the special function <code>infer</code> (default <code>infer</code>)</li>
</ul>
<p>When the special <code>infer</code> function is used the <code>spec</code> and the actual value from the node are compared. If both are versions, according to <code>semver.valid()</code>, <code>eq</code> is used. If both values are ranges, according to <code>!semver.valid()</code>, <code>intersects</code> is used. If the values are mixed types <code>satisfies</code> is used.</p>
<p>Some examples:</p>
<ul>
<li><code>:semver(^1.0.0)</code> returns every node that has a <code>version</code> satisfied by the provided range <code>^1.0.0</code></li>
<li><code>:semver(16.0.0, :attr(engines, [node]))</code> returns every node which has an <code>engines.node</code> property satisfying the version <code>16.0.0</code></li>
<li><code>:semver(1.0.0, [version], lt)</code> every node with a <code>version</code> less than <code>1.0.0</code></li>
<p>The <code>:outdated</code> 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:</p>
<ul>
<li><code>any</code> (default) a version exists that is greater than the current one</li>
<li><code>major</code> a version exists that is a semver major greater than the current one</li>
<li><code>minor</code> a version exists that is a semver minor greater than the current one</li>
<li><code>patch</code> a version exists that is a semver patch greater than the current one</li>
</ul>
<p>In addition to the filtering performed by the pseudo selector, some extra data is added to the resulting objects. The following data can be found under the <code>queryContext</code> property of each node.</p>
<ul>
<li><code>versions</code> an array of every available version of the given node</li>
<li><code>outdated.inRange</code> an array of objects, each with a <code>from</code> and <code>versions</code>, where <code>from</code> is the on-disk location of the node that depends on the current node and <code>versions</code> is an array of all available versions that satisfies that dependency. This is only populated if <code>:outdated(in-range)</code> is used.</li>
<li><code>outdated.outOfRange</code> an array of objects, identical in shape to <code>inRange</code>, but where the <code>versions</code> array is every available version that does not satisfy the dependency. This is only populated if <code>:outdated(out-of-range)</code> is used.</li>
</ul>
<p>Some examples:</p>
<ul>
<li><code>:root > :outdated(major)</code> returns every direct dependency that has a new semver major release</li>
<li><code>.prod:outdated(in-range)</code> returns production dependencies that have a new release that satisfies at least one of its parent's dependencies</li>
</ul>
<h5id="vuln"><code>:vuln</code></h5>
<p>The <code>:vuln</code> 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 <code>semver@7.6.0</code> in your tree, a vulnerability for <code>semver</code> which affects versions <code><=6.3.1</code> will not match.</p>
<p>You can also filter results by certain attributes in advisories. Currently that includes <code>severity</code> and <code>cwe</code>. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.</p>
<p>In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the <code>queryContext</code> attribute of each node under the <code>advisories</code> attribute.</p>
<p>Some examples:</p>
<ul>
<li><code>:root > .prod:vuln</code> returns direct production dependencies with any known vulnerability</li>
<li><code>:vuln([severity=high])</code> returns only dependencies with a vulnerability with a <code>high</code> severity.</li>
<li><code>:vuln([severity=high],[severity=moderate])</code> returns only dependencies with a vulnerability with a <code>high</code> or <code>moderate</code> severity.</li>
<li><code>:vuln([cwe=1333])</code> returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)</li>
<p>The generic <code>:attr()</code> pseudo selector standardizes a pattern which can be used for attribute selection of <code>Object</code>s, <code>Array</code>s or <code>Arrays</code> of <code>Object</code>s accessible via <code>Arborist</code>'s <code>Node.package</code> metadata. This allows for iterative attribute selection beyond top-level <code>String</code> evaluation. The last argument passed to <code>:attr()</code> must be an <code>attribute</code> selector or a nested <code>:attr()</code>. See examples below:</p>
<p><code>Array</code>s specifically uses a special/reserved <code>.</code> character in place of a typical attribute name. <code>Arrays</code> also support exact <code>value</code> matching when a <code>String</code> is passed to the selector.</p>
<h5id="example-of-an-array-attribute-selection">Example of an <code>Array</code> Attribute Selection:</h5>
<p>Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in <code>package.json</code>). This approach is user-centric as the ecosystem has been taught to think about dependencies in these groups first-and-foremost. Dependencies are allowed to be included in multiple groups (ex. a <code>prod</code> dependency may also be a <code>dev</code> dependency (in that it's also required by another <code>dev</code> dependency) & may also be <code>bundled</code> - a selector for that type of dependency would look like: <code>*.prod.dev.bundled</code>).</p>
<ul>
<li><code>.prod</code></li>
<li><code>.dev</code></li>
<li><code>.optional</code></li>
<li><code>.peer</code></li>
<li><code>.bundled</code></li>
<li><code>.workspace</code></li>
</ul>
<p>Please note that currently <code>workspace</code> deps are always <code>prod</code> dependencies. Additionally the <code>.root</code> dependency is also considered a <code>prod</code> dependency.</p>
