feat: add npm query cmd (#5000)

Co-authored-by: Gar <gar+gh@danger.computer>

docs/content/commands/npm-query.md

@@ -0,0 +1,236 @@
+---
+title: npm-query
+section: 1
+description: Dependency selector query
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/query.js -->
+
+```bash
+npm query <selector>
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/query.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
+### Description
+
+The `npm query` command allows for usage of css selectors in order to retrieve
+an array of dependency objects.
+
+### Piping npm query to other commands
+
+```bash
+# find all dependencies with postinstall scripts & uninstall them
+npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
+
+# find all git dependencies & explain who requires them
+npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
+```
+
+### Extended Use Cases & Queries
+
+```stylus
+// all deps
+*
+
+// all direct deps
+:root > *
+
+// direct production deps
+:root > .prod
+
+// direct development deps
+:root > .dev
+
+// any peer dep of a direct deps
+:root > * > .peer
+
+// any workspace dep
+.workspace
+
+// all workspaces that depend on another workspace
+.workspace > .workspace
+
+// all workspaces that have peer deps
+.workspace:has(.peer)
+
+// any dep named "lodash"
+// equivalent to [name="lodash"]
+#lodash
+
+// any deps named "lodash" & within semver range ^"1.2.3"
+#lodash@^1.2.3
+// equivalent to...
+[name="lodash"]:semver(^1.2.3)
+
+// get the hoisted node for a given semver range
+#lodash@^1.2.3:not(:deduped)
+
+// querying deps with a specific version
+#lodash@2.1.5
+// equivalent to...
+[name="lodash"][version="2.1.5"]
+
+// has any deps
+:has(*)
+
+// deps with no other deps (ie. "leaf" nodes)
+:empty
+
+// manually querying git dependencies
+[repository^=github:],
+[repository^=git:],
+[repository^=https://github.com],
+[repository^=http://github.com],
+[repository^=https://github.com],
+[repository^=+git:...]
+
+// querying for all git dependencies
+:type(git)
+
+// get production dependencies that aren't also dev deps
+.prod:not(.dev)
+
+// get dependencies with specific licenses
+[license=MIT], [license=ISC]
+
+// find all packages that have @ruyadorno as a contributor
+:attr(contributors, [email=ruyadorno@github.com])
+```
+
+### Example Response Output
+
+- an array of dependency objects is returned which can contain multiple copies of the same package which may or may not have been linked or deduped
+
+```json
+[
+  {
+    "name": "",
+    "version": "",
+    "description": "",
+    "homepage": "",
+    "bugs": {},
+    "author": {},
+    "license": {},
+    "funding": {},
+    "files": [],
+    "main": "",
+    "browser": "",
+    "bin": {},
+    "man": [],
+    "directories": {},
+    "repository": {},
+    "scripts": {},
+    "config": {},
+    "dependencies": {},
+    "devDependencies": {},
+    "optionalDependencies": {},
+    "bundledDependencies": {},
+    "peerDependencies": {},
+    "peerDependenciesMeta": {},
+    "engines": {},
+    "os": [],
+    "cpu": [],
+    "workspaces": {},
+    "keywords": [],
+    ...
+  },
+  ...
+```
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+#### `global`
+
+* Default: false
+* Type: Boolean
+
+Operates in "global" mode, so that packages are installed into the `prefix`
+folder instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result in selecting all
+  workspaces within that folder)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `workspaces`
+
+* Default: null
+* Type: null or Boolean
+
+Set to true to run the command in the context of **all** configured
+workspaces.
+
+Explicitly setting this to false will cause commands like `install` to
+ignore workspaces altogether. When not set explicitly:
+
+- Commands that operate on the `node_modules` tree (install, update, etc.)
+will link workspaces into the `node_modules` folder. - Commands that do
+other things (test, exec, publish, etc.) will operate on the root project,
+_unless_ one or more workspaces are specified in the `workspace` config.
+
+This value is not exported to the environment for child processes.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `include-workspace-root`
+
+* Default: false
+* Type: Boolean
+
+Include the workspace root when workspaces are enabled for a command.
+
+When false, specifying individual workspaces via the `workspace` config, or
+all workspaces via the `workspaces` flag, will cause npm to operate only on
+the specified workspaces, and not on the root project.
+
+This value is not exported to the environment for child processes.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+## See Also
+
+* [dependency selector](/using-npm/dependency-selector)
+