docs: add documentation for expanded :semver selector

Author: nlf

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

@@ -58,10 +58,31 @@ The [`npm query`](/commands/npm-query) commmand exposes a new dependency selecto
 - `:extraneous` when a dependency exists but is not defined as a dependency of any node
 - `:invalid` when a dependency version is out of its ancestors specified range
 - `:missing` when a dependency is not found on disk
-- `:semver(<spec>)` matching a valid [`node-semver`](https://github.com/npm/node-semver) spec
+- `:semver([spec], [selector], [function])` match a valid [`node-semver`](https://github.com/npm/node-semver) version or range to an optional selector (defaults to `[version]`) and providing an optional semver function name
 - `: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)
 
+##### `:semver([spec], [selector], [function])`
+
+The `:semver()` pseudo selector allows comparing fields from each node's `package.json` using [semver](https://github.com/npm/node-semver#readme) methods. It accepts up to 3 parameters, all of which are optional.
+
+- `spec` a semver version or range (no default)
+- `selector` an attribute selector for each node
+- `function` a semver method to apply, one of: `satisfies`, `intersects`, `subset`, `gt`, `gte`, `gtr`, `lt`, `lte`, `ltr`, `eq` or `neq`
+
+If no `spec` is provided this selector will return every node that defines a `version`.
+
+If only a `spec` is provided `selector` defaults to `[version]` and `function` to `satisfies`.
+
+If a `spec` and a `selector` are provided, the `function` will default to one of `satisfies`, `intersects` or `eq` depending on the value of the `spec` as well as the resulting value of the `selector`. If both values are versions `eq` is used. If both values are ranges `intersects` is used. If the values are mixed types `satisfies` is used. Any other semver method must be passed explicitly.
+
+Some examples:
+
+- `:semver()` returns every node that has a defined `version`
+- `:semver(^1.0.0)` returns every node that has a `version` satisfied by the provided range `^1.0.0`
+- `:semver(16.0.0, :attr(engines, [node]))` returns every node which has an `engines.node` property satisfying the version `16.0.0`
+- `:semver(1.0.0, [version], lt)` every node with a `version` less than `1.0.0`
+
 #### [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.