CLI documentation update from CI
npm CLI robot committed
Aug 2, 2022 at 03:12 UTC
fba5286f719400187cee70199d8dfed284b38d89
5 files changed
+430
-2
cli/v8
+1
-1
@@ -1 +1 @@
1
-Subproject commit 58cc362ceec82ddeb16311d3fb574908294ac789
1
+Subproject commit 3c024ace60904c69e61da00e1fb56c0c1735804a
content/cli/v8/commands/npm-ci.md
+1
-1
@@ -77,7 +77,7 @@ $ npm ci
77
added 154 packages in 5s
78
```
79
80
-Configure Travis to build using `npm ci` instead of `npm install`:
80
+Configure Travis CI to build using `npm ci` instead of `npm install`:
81
82
```bash
83
# .travis.yml
content/cli/v8/commands/npm-query.md
new
+246
@@ -0,0 +1,246 @@
1
+---
2
+title: npm-query
3
+section: 1
4
+description: Dependency selector query
5
+redirect_from:
6
+ - /cli/query
7
+ - /cli/query.html
8
+ - /cli/commands/query
9
+ - /cli-commands/query
10
+ - /cli-commands/query.html
11
+ - /cli-commands/npm-query
12
+github_repo: npm/cli
13
+github_branch: latest
14
+github_path: docs/content/commands/npm-query.md
15
+---
16
+
17
+### Synopsis
18
+
19
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
20
+<!-- automatically generated, do not edit manually -->
21
+<!-- see lib/commands/query.js -->
22
+
23
+```bash
24
+npm query <selector>
25
+```
26
+
27
+<!-- automatically generated, do not edit manually -->
28
+<!-- see lib/commands/query.js -->
29
+
30
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
31
+
32
+### Description
33
+
34
+The `npm query` command allows for usage of css selectors in order to retrieve
35
+an array of dependency objects.
36
+
37
+### Piping npm query to other commands
38
+
39
+```bash
40
+# find all dependencies with postinstall scripts & uninstall them
41
+npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
42
+
43
+# find all git dependencies & explain who requires them
44
+npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
45
+```
46
+
47
+### Extended Use Cases & Queries
48
+
49
+```stylus
50
+// all deps
51
+*
52
+
53
+// all direct deps
54
+:root > *
55
+
56
+// direct production deps
57
+:root > .prod
58
+
59
+// direct development deps
60
+:root > .dev
61
+
62
+// any peer dep of a direct deps
63
+:root > * > .peer
64
+
65
+// any workspace dep
66
+.workspace
67
+
68
+// all workspaces that depend on another workspace
69
+.workspace > .workspace
70
+
71
+// all workspaces that have peer deps
72
+.workspace:has(.peer)
73
+
74
+// any dep named "lodash"
75
+// equivalent to [name="lodash"]
76
+#lodash
77
+
78
+// any deps named "lodash" & within semver range ^"1.2.3"
79
+#lodash@^1.2.3
80
+// equivalent to...
81
+[name="lodash"]:semver(^1.2.3)
82
+
83
+// get the hoisted node for a given semver range
84
+#lodash@^1.2.3:not(:deduped)
85
+
86
+// querying deps with a specific version
87
+#lodash@2.1.5
88
+// equivalent to...
89
+[name="lodash"][version="2.1.5"]
90
+
91
+// has any deps
92
+:has(*)
93
+
94
+// deps with no other deps (ie. "leaf" nodes)
95
+:empty
96
+
97
+// manually querying git dependencies
98
+[repository^=github:],
99
+[repository^=git:],
100
+[repository^=https://github.com],
101
+[repository^=http://github.com],
102
+[repository^=https://github.com],
103
+[repository^=+git:...]
104
+
105
+// querying for all git dependencies
106
+:type(git)
107
+
108
+// get production dependencies that aren't also dev deps
109
+.prod:not(.dev)
110
+
111
+// get dependencies with specific licenses
112
+[license=MIT], [license=ISC]
113
+
114
+// find all packages that have @ruyadorno as a contributor
115
+:attr(contributors, [email=ruyadorno@github.com])
116
+```
117
+
118
+### Example Response Output
119
+
120
+- 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
121
+
122
+```json
123
+[
124
+ {
125
+ "name": "",
126
+ "version": "",
127
+ "description": "",
128
+ "homepage": "",
129
+ "bugs": {},
130
+ "author": {},
131
+ "license": {},
132
+ "funding": {},
133
+ "files": [],
134
+ "main": "",
135
+ "browser": "",
136
+ "bin": {},
137
+ "man": [],
138
+ "directories": {},
139
+ "repository": {},
140
+ "scripts": {},
141
+ "config": {},
142
+ "dependencies": {},
143
+ "devDependencies": {},
144
+ "optionalDependencies": {},
145
+ "bundledDependencies": {},
146
+ "peerDependencies": {},
147
+ "peerDependenciesMeta": {},
148
+ "engines": {},
149
+ "os": [],
150
+ "cpu": [],
151
+ "workspaces": {},
152
+ "keywords": [],
153
+ ...
154
+ },
155
+ ...
156
+```
157
+
158
+### Configuration
159
+
160
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
161
+<!-- automatically generated, do not edit manually -->
162
+<!-- see lib/utils/config/definitions.js -->
163
+#### `global`
164
+
165
+* Default: false
166
+* Type: Boolean
167
+
168
+Operates in "global" mode, so that packages are installed into the `prefix`
169
+folder instead of the current working directory. See
170
+[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.
171
+
172
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
173
+ of the current working directory.
174
+* bin files are linked to `{prefix}/bin`
175
+* man pages are linked to `{prefix}/share/man`
176
+
177
+<!-- automatically generated, do not edit manually -->
178
+<!-- see lib/utils/config/definitions.js -->
179
+
180
+#### `workspace`
181
+
182
+* Default:
183
+* Type: String (can be set multiple times)
184
+
185
+Enable running a command in the context of the configured workspaces of the
186
+current project while filtering by running only the workspaces defined by
187
+this configuration option.
188
+
189
+Valid values for the `workspace` config are either:
190
+
191
+* Workspace names
192
+* Path to a workspace directory
193
+* Path to a parent workspace directory (will result in selecting all
194
+ workspaces within that folder)
195
+
196
+When set for the `npm init` command, this may be set to the folder of a
197
+workspace which does not yet exist, to create the folder and set it up as a
198
+brand new workspace within the project.
199
+
200
+This value is not exported to the environment for child processes.
201
+
202
+<!-- automatically generated, do not edit manually -->
203
+<!-- see lib/utils/config/definitions.js -->
204
+
205
+#### `workspaces`
206
+
207
+* Default: null
208
+* Type: null or Boolean
209
+
210
+Set to true to run the command in the context of **all** configured
211
+workspaces.
212
+
213
+Explicitly setting this to false will cause commands like `install` to
214
+ignore workspaces altogether. When not set explicitly:
215
+
216
+- Commands that operate on the `node_modules` tree (install, update, etc.)
217
+will link workspaces into the `node_modules` folder. - Commands that do
218
+other things (test, exec, publish, etc.) will operate on the root project,
219
+_unless_ one or more workspaces are specified in the `workspace` config.
220
+
221
+This value is not exported to the environment for child processes.
222
+
223
+<!-- automatically generated, do not edit manually -->
224
+<!-- see lib/utils/config/definitions.js -->
225
+
226
+#### `include-workspace-root`
227
+
228
+* Default: false
229
+* Type: Boolean
230
+
231
+Include the workspace root when workspaces are enabled for a command.
232
+
233
+When false, specifying individual workspaces via the `workspace` config, or
234
+all workspaces via the `workspaces` flag, will cause npm to operate only on
235
+the specified workspaces, and not on the root project.
236
+
237
+This value is not exported to the environment for child processes.
238
+
239
+<!-- automatically generated, do not edit manually -->
240
+<!-- see lib/utils/config/definitions.js -->
241
+
242
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
243
+## See Also
244
+
245
+* [dependency selector](/cli/v8/using-npm/dependency-selector)
246
+
content/cli/v8/using-npm/dependency-selectors.md
new
+176
@@ -0,0 +1,176 @@
1
+---
2
+title: Dependency Selector Syntax & Querying
3
+section: 7
4
+description: Dependency Selector Syntax & Querying
5
+redirect_from:
6
+ - /using-npm/dependency-selectors
7
+ - /using-npm/dependency-selectors.html
8
+ - /misc/dependency-selectors
9
+ - /misc/dependency-selectors.html
10
+github_repo: npm/cli
11
+github_branch: latest
12
+github_path: docs/content/using-npm/dependency-selectors.md
13
+---
14
+
15
+### Description
16
+
17
+The [`npm query`](/cli/v8/commands/npm-query) commmand exposes a new dependency selector syntax (informed by & respecting many aspects of the [CSS Selectors 4 Spec](https://dev.w3.org/csswg/selectors4/#relational)) which:
18
+
19
+- Standardizes the shape of, & querying of, dependency graphs with a robust object model, metadata & selector syntax
20
+- Leverages existing, known language syntax & operators from CSS to make disparate package information broadly accessible
21
+- Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
22
+- Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
23
+
24
+### Dependency Selector Syntax `v1.0.0`
25
+
26
+#### Overview:
27
+
28
+- there is no "type" or "tag" selectors (ex. `div, h1, a`) as a dependency/target is the only type of `Node` that can be queried
29
+- the term "dependencies" is in reference to any `Node` found in a `tree` returned by `Arborist`
30
+
31
+#### Combinators
32
+
33
+- `>` direct descendant/child
34
+- ` ` any descendant/child
35
+- `~` sibling
36
+
37
+#### Selectors
38
+
39
+- `*` universal selector
40
+- `#<name>` dependency selector (equivalent to `[name="..."]`)
41
+- `#<name>@<version>` (equivalent to `[name=<name>]:semver(<version>)`)
42
+- `,` selector list delimiter
43
+- `.` dependency type selector
44
+- `:` pseudo selector
45
+
46
+#### Dependency Type Selectors
47
+
48
+- `.prod` dependency found in the `dependencies` section of `package.json`, or is a child of said dependency
49
+- `.dev` dependency found in the `devDependencies` section of `package.json`, or is a child of said dependency
50
+- `.optional` dependency found in the `optionalDependencies` section of `package.json`, or has `"optional": true` set in its entry in the `peerDependenciesMeta` section of `package.json`, or a child of said dependency
51
+- `.peer` dependency found in the `peerDependencies` section of `package.json`
52
+- `.workspace` dependency found in the [`workspaces`](https://docs.npmjs.com/cli/v8/using-npm/workspaces) section of `package.json`
53
+- `.bundled` dependency found in the `bundleDependencies` section of `package.json`, or is a child of said dependency
54
+
55
+#### Pseudo Selectors
56
+- [`:not(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
57
+- [`:has(<selector>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)
58
+- [`:is(<selector list>)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:is)
59
+- [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) matches the root node/dependency
60
+- [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) matches node/dependency it was queried against
61
+- [`:empty`](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty) when a dependency has no dependencies
62
+- [`:private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) when a dependency is private
63
+- `:link` when a dependency is linked (for instance, workspaces or packages manually [`linked`](https://docs.npmjs.com/cli/v8/commands/npm-link)
64
+- `:deduped` when a dependency has been deduped (note that this does *not* always mean the dependency has been hoisted to the root of node_modules)
65
+- `:override` when a dependency is an override (not implemented yet)
66
+- `:extraneous` when a dependency exists but is not defined as a dependency of any node
67
+- `:invalid` when a dependency version is out of its ancestors specified range
68
+- `:missing` when a dependency is not found on disk
69
+- `:semver(<spec>)` matching a valid [`node-semver`](https://github.com/npm/node-semver) spec
70
+- `:path(<path>)` [glob](https://www.npmjs.com/package/glob) matching based on dependencies path relative to the project
71
+- `:type(<type>)` [based on currently recognized types](https://github.com/npm/npm-package-arg#result-object)
72
+
73
+#### [Attribute Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
74
+
75
+The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
76
+
77
+- `[]` attribute selector (ie. existence of attribute)
78
+- `[attribute=value]` attribute value is equivalant...
79
+- `[attribute~=value]` attribute value contains word...
80
+- `[attribute*=value]` attribute value contains string...
81
+- `[attribute|=value]` attribute value is equal to or starts with...
82
+- `[attribute^=value]` attribute value starts with...
83
+- `[attribute$=value]` attribute value ends with...
84
+
85
+#### `Array` & `Object` Attribute Selectors
86
+
87
+The generic `:attr()` pseudo selector standardizes a pattern which can be used for attribute selection of `Object`s, `Array`s or `Arrays` of `Object`s accessible via `Arborist`'s `Node.package` metadata. This allows for iterative attribute selection beyond top-level `String` evaluation. The last argument passed to `:attr()` must be an `attribute` selector or a nested `:attr()`. See examples below:
88
+
89
+#### `Objects`
90
+
91
+```css
92
+/* return dependencies that have a `scripts.test` containing `"tap"` */
93
+*:attr(scripts, [test~=tap])
94
+```
95
+
96
+#### Nested `Objects`
97
+
98
+Nested objects are expressed as sequential arguments to `:attr()`.
99
+
100
+```css
101
+/* return dependencies that have a testling config for opera browsers */
102
+*:attr(testling, browsers, [~=opera])
103
+```
104
+
105
+#### `Arrays`
106
+
107
+`Array`s specifically uses a special/reserved `.` character in place of a typical attribute name. `Arrays` also support exact `value` matching when a `String` is passed to the selector.
108
+
109
+##### Example of an `Array` Attribute Selection:
110
+```css
111
+/* removes the distinction between properties & arrays */
112
+/* ie. we'd have to check the property & iterate to match selection */
113
+*:attr([keywords^=react])
114
+*:attr(contributors, :attr([name~=Jordan]))
115
+```
116
+
117
+##### Example of an `Array` matching directly to a value:
118
+```css
119
+/* return dependencies that have the exact keyword "react" */
120
+/* this is equivalent to `*:keywords([value="react"])` */
121
+*:attr([keywords=react])
122
+```
123
+
124
+##### Example of an `Array` of `Object`s:
125
+```css
126
+/* returns */
127
+*:attr(contributors, [email=ruyadorno@github.com])
128
+```
129
+
130
+### Groups
131
+
132
+Dependency groups are defined by the package relationships to their ancestors (ie. the dependency types that are defined in `package.json`). 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 `prod` dependency may also be a `dev` dependency (in that it's also required by another `dev` dependency) & may also be `bundled` - a selector for that type of dependency would look like: `*.prod.dev.bundled`).
133
+
134
+- `.prod`
135
+- `.dev`
136
+- `.optional`
137
+- `.peer`
138
+- `.bundled`
139
+- `.workspace`
140
+
141
+Please note that currently `workspace` deps are always `prod` dependencies. Additionally the `.root` dependency is also considered a `prod` dependency.
142
+
143
+### Programmatic Usage
144
+
145
+- `Arborist`'s `Node` Class has a `.querySelectorAll()` method
146
+ - this method will return a filtered, flattened dependency Arborist `Node` list based on a valid query selector
147
+
148
+```js
149
+const Arborist = require('@npmcli/arborist')
150
+const arb = new Arborist({})
151
+```
152
+
153
+```js
154
+// root-level
155
+arb.loadActual((tree) => {
156
+ // query all production dependencies
157
+ const results = await tree.querySelectorAll('.prod')
158
+ console.log(results)
159
+})
160
+```
161
+
162
+```js
163
+// iterative
164
+arb.loadActual((tree) => {
165
+ // query for the deduped version of react
166
+ const results = await tree.querySelectorAll('#react:not(:deduped)')
167
+ // query the deduped react for git deps
168
+ const deps = await results[0].querySelectorAll(':type(git)')
169
+ console.log(deps)
170
+})
171
+```
172
+
173
+## See Also
174
+
175
+* [npm query](/cli/v8/commands/npm-query)
176
+* [@npmcli/arborist](https://npm.im/@npmcli/arborist]
src/gatsby-theme-doctornpm/nav.yml
+6
@@ -914,6 +914,9 @@
914
- title: npm publish
915
url: /cli/v8/commands/npm-publish
916
description: Publish a package
917
+ - title: npm query
918
+ url: /cli/v8/commands/npm-query
919
+ description: Retrieve a filtered list of packages
920
- title: npm rebuild
921
url: /cli/v8/commands/npm-rebuild
922
description: Rebuild a package
@@ -1033,6 +1036,9 @@
1036
- title: Organizations
1037
url: /cli/v8/using-npm/orgs
1038
description: Working with teams & organizations
1039
+ - title: Dependency Selectors
1040
+ url: /cli/v8/using-npm/dependency-selectors
1041
+ description: Dependency Selector Syntax & Querying
1042
- title: Developers
1043
url: /cli/v8/using-npm/developers
1044
description: Developer guide