@convesoft/nx-rust 1.0.0-rc.1 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/PLUGIN.md +106 -0
  2. package/README.md +8 -4
  3. package/docs/artifacts.mara.md +374 -0
  4. package/docs/caching.mara.md +999 -0
  5. package/docs/ci.mara.md +308 -0
  6. package/docs/configuration.mara.md +508 -0
  7. package/docs/decisions.mara.md +3267 -0
  8. package/docs/execution.mara.md +533 -0
  9. package/docs/index.mara.md +51 -0
  10. package/docs/product.mara.md +366 -0
  11. package/docs/release.mara.md +493 -0
  12. package/docs/setup.mara.md +486 -0
  13. package/docs/targets.mara.md +704 -0
  14. package/docs/testing.mara.md +431 -0
  15. package/docs/verification.mara.md +465 -0
  16. package/docs/workspaces.mara.md +445 -0
  17. package/package.json +1 -1
  18. package/src/cargo/build-settings.d.ts +8 -1
  19. package/src/cargo/build-settings.js +21 -11
  20. package/src/cargo/build-settings.js.map +1 -1
  21. package/src/cargo/metadata.d.ts +2 -0
  22. package/src/cargo/metadata.js.map +1 -1
  23. package/src/cargo/redirections.d.ts +4 -1
  24. package/src/cargo/redirections.js +7 -2
  25. package/src/cargo/redirections.js.map +1 -1
  26. package/src/cargo/warnings-setting.d.ts +24 -0
  27. package/src/cargo/warnings-setting.js +81 -0
  28. package/src/cargo/warnings-setting.js.map +1 -0
  29. package/src/executors/cargo/schema.json +4 -0
  30. package/src/executors/cargo-output.d.ts +8 -2
  31. package/src/executors/cargo-output.js +20 -6
  32. package/src/executors/cargo-output.js.map +1 -1
  33. package/src/executors/command.d.ts +13 -0
  34. package/src/executors/command.js +37 -7
  35. package/src/executors/command.js.map +1 -1
  36. package/src/executors/denied-warnings.d.ts +99 -0
  37. package/src/executors/denied-warnings.js +188 -0
  38. package/src/executors/denied-warnings.js.map +1 -0
  39. package/src/executors/group-run.d.ts +1 -1
  40. package/src/executors/group-run.js +23 -13
  41. package/src/executors/group-run.js.map +1 -1
  42. package/src/executors/groups.d.ts +7 -2
  43. package/src/executors/groups.js +22 -3
  44. package/src/executors/groups.js.map +1 -1
  45. package/src/executors/nextest.d.ts +6 -2
  46. package/src/executors/nextest.js +12 -6
  47. package/src/executors/nextest.js.map +1 -1
  48. package/src/executors/task-guards.js +7 -2
  49. package/src/executors/task-guards.js.map +1 -1
  50. package/src/executors/task.js +10 -3
  51. package/src/executors/task.js.map +1 -1
  52. package/src/executors/test-mode.d.ts +4 -1
  53. package/src/executors/test-mode.js +7 -1
  54. package/src/executors/test-mode.js.map +1 -1
  55. package/src/executors/test-steps.d.ts +20 -8
  56. package/src/executors/test-steps.js +45 -14
  57. package/src/executors/test-steps.js.map +1 -1
  58. package/src/graph/caching.js +5 -0
  59. package/src/graph/caching.js.map +1 -1
  60. package/src/graph/clippy-input.d.ts +53 -0
  61. package/src/graph/clippy-input.js +107 -0
  62. package/src/graph/clippy-input.js.map +1 -0
  63. package/src/graph/collisions.d.ts +7 -0
  64. package/src/graph/collisions.js.map +1 -1
  65. package/src/graph/discovery.d.ts +15 -0
  66. package/src/graph/discovery.js +5 -0
  67. package/src/graph/discovery.js.map +1 -1
  68. package/src/graph/inputs.d.ts +3 -1
  69. package/src/graph/inputs.js +11 -1
  70. package/src/graph/inputs.js.map +1 -1
  71. package/src/graph/projects.js +13 -2
  72. package/src/graph/projects.js.map +1 -1
  73. package/src/graph/rustfmt-config.d.ts +42 -0
  74. package/src/graph/rustfmt-config.js +173 -0
  75. package/src/graph/rustfmt-config.js.map +1 -0
  76. package/src/graph/targets.d.ts +11 -7
  77. package/src/graph/targets.js +12 -8
  78. package/src/graph/targets.js.map +1 -1
@@ -0,0 +1,704 @@
1
+ # Targets
2
+
3
+ > **Status:** the plugin infers the targets of this page. `test`
4
+ > runs `cargo test`, or nextest where the workspace's `testRunner` says so.
5
+ > `build`, `napi-build`, `wasm-build` and `doc` run
6
+ > the executor `@convesoft/nx-rust:cargo-outputs`, the other cargo targets
7
+ > `@convesoft/nx-rust:cargo`, and the tasks of one group share their cargo
8
+ > calls ([Batching and features](execution.mara.md)).
9
+
10
+ The plugin infers targets from the shape of each crate and of each Cargo
11
+ workspace. Nothing is declared per crate.
12
+
13
+ | Target | Runs | Exists on | Cached | Outputs |
14
+ | -------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
15
+ | `build` | `cargo build` | Every crate | Yes | Final artifacts only: executables, `cdylib` and `staticlib` files |
16
+ | `check` | `cargo check --all-targets` | Every crate | Yes | None; the result only |
17
+ | `lint` | `cargo clippy --all-targets` | Every crate | Yes | None; the result only |
18
+ | `test` | `cargo test` or nextest | Every crate | Yes | None; the result only |
19
+ | `fmt-check` | `cargo fmt --check` | Every crate | Yes | None; the result only |
20
+ | `fmt` | `cargo fmt` | Every crate | No | None |
21
+ | `bench` | `cargo bench` | Crates with a bench target | No | None |
22
+ | `run` | `cargo run` | Crates with a binary target | No | None |
23
+ | `napi-build`, `wasm-build` | See [napi and wasm artifacts](artifacts.mara.md) | Crates that produce that artifact | Yes | The package files |
24
+ | `nx-release-publish` | `cargo publish` | Crates without `publish = false`, apart from a hack crate | No | None |
25
+ | `doc` | `cargo doc --no-deps --workspace` | The workspace project | Yes | The workspace's whole doc folder |
26
+ | `audit` | `cargo audit` | The workspace project | No | None |
27
+ | `deny` | `cargo deny check` | The workspace project, where cargo-deny is set up | No | None |
28
+ | `update` | `cargo update` | The workspace project | No | None |
29
+ | `lockfile` | `cargo update --workspace`, then a digest per crate | The workspace project | No | The digests, in `.nx/workspace-data` |
30
+ | `hakari-check` | `cargo hakari generate --diff`, `cargo hakari manage-deps --dry-run` | The workspace project, where the workspace uses the `hakari` feature strategy | No | None |
31
+ | `coverage-baseline` | `cargo affected collect`, then the record of its context | The workspace project, where the workspace turns on `affectedTests` | No | None |
32
+
33
+ A crate's targets select it with `-p` and its package ID specification, which
34
+ cargo gives each task, and `fmt` and `fmt-check` with its package name. Every
35
+ command starts in the root folder of the crate's workspace
36
+ ([Caching](caching.mara.md#where-cargo-runs)). With `--verbose`, each task
37
+ prints its exact command before it runs
38
+ ([Seeing the command](caching.mara.md#seeing-the-command)).
39
+
40
+ ```sh
41
+ nx test api # one crate
42
+ nx run-many -t lint test # every project, JS and Rust
43
+ nx affected -t lint test build # only what the change affects
44
+ nx run api:run -- --port 3000 # run a binary with arguments
45
+ nx test api --test=performance # one integration test target
46
+ ```
47
+
48
+ Names can be changed in the plugin options, and options of a target can be set
49
+ per crate or per workspace: see [Configuration](configuration.mara.md).
50
+
51
+ ## Checking all targets
52
+
53
+ `check` and `lint` cover the tests, benches and examples of a crate too, because
54
+ they pass `--all-targets`. rust-analyzer checks the same way by default, so the
55
+ editor and Nx compile the same things and reuse each other's work
56
+ ([[EVD-CARGO-TARGET-COMMANDS]]).
57
+
58
+ The flag comes from an option of the target that is on by default. A crate whose
59
+ benches need a nightly compiler, which stable rejects under `--all-targets`, can
60
+ switch it off in its `[package.metadata.nx.targets.check.options]` and
61
+ `[package.metadata.nx.targets.lint.options]` with `allTargets = false`.
62
+
63
+ ## Warnings
64
+
65
+ No target adds a flag that turns warnings into errors: `lint` fails where
66
+ `cargo clippy` fails. To fail on warnings, say so where Cargo reads it:
67
+
68
+ - lint levels in `[lints]` or `[workspace.lints]` of your manifests,
69
+ - `build.warnings = "deny"` in `.cargo/config.toml`, or
70
+ `CARGO_BUILD_WARNINGS=deny` for one run, such as in CI,
71
+ - `RUSTFLAGS="-D warnings"`, which also rebuilds every dependency.
72
+
73
+ ```toml
74
+ # rust/.cargo/config.toml
75
+ [build]
76
+ warnings = "deny"
77
+ ```
78
+
79
+ All of these are part of the cache key, so a result that passed with warnings
80
+ allowed is never reused where they are denied. Cargo honours `build.warnings`
81
+ from 1.97 on; older versions ignore it without a word
82
+ ([[EVD-CARGO-TARGET-COMMANDS]]).
83
+
84
+ Cargo ignores `build.warnings` in the JSON compile steps: the commands of
85
+ `build`, `check`, `lint`, `napi-build` and `wasm-build` that several tasks share,
86
+ or that select the whole workspace, which read cargo's JSON messages to tell the
87
+ crates apart, and the compile of `napi-build` and `wasm-build` also for one
88
+ crate. There the plugin applies the setting itself. Where warnings are denied
89
+ and the command reports a warning, every task of that command fails, also one
90
+ whose crate does not use the crate with the warning, because cargo does not
91
+ say which crates a warning fails. Under `workspace-build` the command compiles
92
+ with the whole workspace's features, so a warning that only your crate's own
93
+ features produce is not reported there. Cargo's own verdict applies where a task
94
+ runs its crate's plain command alone and in the `test` steps.
95
+
96
+ ## Running binaries
97
+
98
+ `nx run api` is Nx's own syntax and needs a target, so `run` is started as
99
+ `nx run api:run`. Arguments after `--` go to the binary, and so does the value
100
+ of the `args` option:
101
+
102
+ ```sh
103
+ nx run api:run -- --port 3000
104
+ nx run api:run --bin server --args="--port 3000"
105
+ ```
106
+
107
+ Use `--args` when you also pass a flag to Nx or to `run`, such as `--bin`: when
108
+ the command has `--`, Nx drops the flags before it that it does not know.
109
+ Use it also when an argument has the name of one of `run`'s options, such as
110
+ `--profile`, which Nx would otherwise check as that option and can reject.
111
+ Write `--args` with `=`, and give it once. Quotes inside its value group words
112
+ as in a shell, and nothing in it is expanded. A value that is only a number
113
+ needs a blank, as in `--args=" 3000"`, or goes after `--`, because Nx would
114
+ otherwise read it as a number and reject it.
115
+
116
+ A crate with several binaries needs to say which one `run` starts: set
117
+ `default-run` in its `[package]` table, or pass the binary through the `bin`
118
+ option of the `run` target, on the command line as in `nx run api:run
119
+ --bin=migrate` or in the crate's metadata. Without either, cargo stops and
120
+ lists the binaries.
121
+
122
+ `run` is not a continuous task: a target that depends on it waits until the
123
+ binary exits, which is what a code generator or a migration needs. A crate that
124
+ serves something, such as an API that end-to-end tests talk to, makes its `run`
125
+ continuous and tells Nx when it is ready:
126
+
127
+ ```toml
128
+ # rust/crates/api/Cargo.toml
129
+ [package.metadata.nx.targets.run]
130
+ continuous = true
131
+ readyWhen = { port = 3000 }
132
+ ```
133
+
134
+ A target that depends on it with `"waitFor": "ready"` then starts once the port
135
+ answers. Restarting the binary when its sources change is not part of v1
136
+ ([[REQ-RUN-WATCH]]).
137
+
138
+ `nx run-many -t run` starts each binary in its own cargo call: `run` tasks are
139
+ never batched.
140
+
141
+ `run` builds the binary as `cargo run` does and leaves it in the artifact
142
+ directory. With the options of `build`, it is the executable that `build`
143
+ writes. With other features or another profile, it replaces that executable
144
+ until the next `build`, run or restored from the cache, puts it back. `run` is
145
+ not cached and Nx does not order it after `build`, so do not run a crate's
146
+ `run` with other options in the same command as its `build` or `test`: the
147
+ `build` could store the executable of `run`, or the tests could run it.
148
+
149
+ ## Tests that build a crate's binaries
150
+
151
+ For a crate with a binary and an integration test, `cargo test` builds the
152
+ binary again, with what the crate's dev-dependencies turn on and with
153
+ `[profile.test]`, and puts it where `cargo build` put its own, such as
154
+ `target/debug/api`. The tests run it from there as `CARGO_BIN_EXE_api`. So that
155
+ Nx never stores one of the two under the other's key, and the tests always run
156
+ their own, `test` waits for the crate's own `build` in such crates. Under the
157
+ `workspace-build` strategy, every test run compiles the tests of the whole
158
+ workspace and so builds the binaries of every such crate: there, the `test` of
159
+ every crate of the workspace waits for the `build` of each of them.
160
+
161
+ ```sh
162
+ nx test api # runs or restores api:build, then runs api:test
163
+ nx test core # also runs or restores api:build first
164
+ nx run-many -t build test # the tests start once those builds have ended
165
+ ```
166
+
167
+ - **Which crates.** Those with a binary and an integration test in `tests/` or
168
+ under `[[test]]`, with or without `harness = false`, or a bench with
169
+ `test = true`, whose tests `cargo test` runs. A `[[test]]` with
170
+ `test = false` counts too, because the `test` option runs it
171
+ ([One test target](testing.mara.md#one-test-target)). Examples, unit tests,
172
+ doctests, a bench without `test` and libraries do not count.
173
+ - **What it costs.** `nx test api`, `nx test core` and `nx affected -t test`
174
+ also run or restore `api:build`. With a warm build directory that is one
175
+ quick task more; on a cold one, cargo also compiles what differs between the
176
+ two executables, which plain `cargo build` would compile as well. A command
177
+ that names both targets only orders them. Nx counts a task's dependencies in
178
+ its cache key and in `nx affected`, so a change to `api` runs the tests of
179
+ every crate of the workspace again, which under `workspace-build` share
180
+ their cargo commands.
181
+ - **What is left on disk.** After a run of both, `target/debug/api` is the
182
+ executable that `cargo test` built, as after plain
183
+ `cargo build && cargo test`. The next `nx build api`, run or restored from
184
+ the cache, puts the one of `build` back. The cache entries are right either
185
+ way.
186
+ - **Your own `dependsOn`.** Keep the plugin's entries with `"..."` when you
187
+ change the `dependsOn` of such a `test`, as in
188
+ `"dependsOn": ["...", "^codegen"]`. Without them, a `test` task whose
189
+ command also runs or restores the crate's `build` fails before cargo runs and
190
+ says so; `nx test api` alone still runs. A dependency on a continuous task,
191
+ such as a server the tests talk to, keeps the order only where that task, or
192
+ a task it depends on, depends on `build` itself.
193
+ - **What it cannot order.** Two `nx` commands started at the same time in one
194
+ checkout, `run` with other options than `build`, and two crates whose
195
+ binaries have the same name can still write one file while the other's
196
+ `build` ends.
197
+
198
+ ## Workspace-level targets
199
+
200
+ Each Cargo workspace has one project for the tasks that concern the whole
201
+ workspace ([Workspaces](workspaces.mara.md#workspace-level-tasks)). It carries
202
+ these targets:
203
+
204
+ - **`doc`** documents every member into the `doc` folder of the workspace's
205
+ artifact directory, as one site with one search index. A cache hit restores
206
+ the whole folder. If two workspaces share one artifact directory, for example
207
+ through a `target-dir` set above both, `doc` runs uncached and the plugin says
208
+ so: restoring one workspace's folder would delete the other's pages. It
209
+ passes `--no-deps`; with `noDeps = false` in
210
+ `[workspace.metadata.nx.project.targets.doc.options]` it documents the
211
+ dependencies too.
212
+ - **`audit`** runs `cargo audit` against the workspace's `Cargo.lock`, with the
213
+ settings in `.cargo/audit.toml` of the workspace root.
214
+ - **`deny`** runs `cargo deny check`. It exists only where `deny.toml`,
215
+ `.deny.toml` or `.cargo/deny.toml` is in the workspace root, because without
216
+ a configuration cargo-deny rejects every license.
217
+ - **`update`** runs `cargo update` and writes `Cargo.lock`. It never passes
218
+ `--locked`, also with the `locked` option or `NX_RUST_LOCKED=true`, because
219
+ changing the lockfile is its purpose.
220
+ - **`lockfile`** runs `cargo update --workspace`, which brings `Cargo.lock` up
221
+ to date as your next `cargo build` would, and writes one digest per crate of
222
+ the packages the crate reaches. It is not cached and runs in every run. Every
223
+ cached task of a crate except `fmt-check` waits for it and reads the crate's
224
+ digest, so a dependency update reruns only the crates it reaches, where the
225
+ workspace uses the `hakari` feature strategy; under `workspace-build` and
226
+ `cargo` it reruns them all ([Caching](caching.mara.md#lockfile-changes)).
227
+ - **`hakari-check`**, where the workspace uses the `hakari` feature strategy,
228
+ runs `cargo hakari generate --diff` and `cargo hakari manage-deps --dry-run`
229
+ after `lockfile`. It is not cached, and the same crate tasks wait for it, so
230
+ none of them runs while the hack crate is stale
231
+ ([Batching and features](execution.mara.md#when-the-hack-crate-is-enough)).
232
+ - **`coverage-baseline`**, in a workspace with `affectedTests`, brings the
233
+ coverage baseline of the affected tests up to date with
234
+ `cargo affected collect` and records the context it collected in. It is not
235
+ cached ([Continuous integration](ci.mara.md#the-coverage-baseline)).
236
+
237
+ ```sh
238
+ nx run-many -t audit deny # every workspace
239
+ ```
240
+
241
+ `audit`, `deny` and `update` are not cached. cargo-audit and cargo-deny fetch
242
+ the RustSec advisory database each time, so the same `Cargo.lock` can fail
243
+ tomorrow that passes today ([[EVD-CARGO-AUDIT-DENY]]). `nx affected` still
244
+ selects them when `Cargo.lock`, the root `Cargo.toml` or the tool's
245
+ configuration changes, and `deny` also when a member's manifest does.
246
+
247
+ The targets exist whether or not cargo-audit and cargo-deny are installed, so
248
+ every machine sees the same projects and targets. A task whose tool is missing
249
+ fails and says how to get it ([Setup](setup.mara.md)).
250
+
251
+ ## No `^build` between crates
252
+
253
+ In JS projects a `build` target often depends on `^build`, the builds of its
254
+ dependencies. Rust targets do not: Cargo builds a crate's dependencies itself,
255
+ and `^` inputs make a change in a dependency invalidate the dependent's cache.
256
+
257
+ Adding `^build` between crates only queues extra cargo processes behind the
258
+ build lock. In one repository that inherited `^build` onto its Rust crates, a
259
+ 52-second test run took 40 minutes ([[EVD-NXRUST-BUILD-DEPS]]).
260
+
261
+ Check your `nx.json`: a target default keyed by a bare target name applies to
262
+ Rust targets with that name too, unless an entry keyed by their executor comes
263
+ first, as the one that `nx add` adds does.
264
+
265
+ ```json
266
+ {
267
+ "targetDefaults": {
268
+ "build": { "dependsOn": ["^build"] }
269
+ }
270
+ }
271
+ ```
272
+
273
+ Such an entry replaces the `dependsOn` of the Rust `build` targets, which
274
+ depend on their workspace's `lockfile` task, so it fails graph creation. With
275
+ `"..."`, as in `["...", "^build"]`, it keeps that dependency and adds `^build`,
276
+ and the plugin warns. Either way the message says how to narrow the entry: see
277
+ [Target defaults that reach Rust targets](#target-defaults-that-reach-rust-targets).
278
+
279
+ A JS project that consumes a Rust crate depends on the crate's artifact target:
280
+ see [napi and wasm artifacts](artifacts.mara.md). The plugin adds no `^build`
281
+ to JS projects, and it cannot take yours away. If a JS target declares `^build`
282
+ and its project depends on a crate, Nx also runs that crate's native `build`.
283
+ It stops there, because the crate's `build` depends only on the `lockfile`
284
+ task of its workspace and, with the `hakari` feature strategy, its
285
+ `hakari-check` task. Where the crate's folder also is a JS package whose
286
+ script or TypeScript build replaced cargo's `build`, Nx runs that instead, and
287
+ if it declares `^build` itself, the native `build` of the crates behind it
288
+ ([napi and wasm artifacts](artifacts.mara.md#a-crate-that-is-also-a-js-package)).
289
+
290
+ ## Target defaults that reach Rust targets
291
+
292
+ A `targetDefaults` entry in `nx.json` keyed by a target's name, such as
293
+ `build`, `lint` or `test`, applies to the Rust targets of that name too, and
294
+ one keyed by an executor of the plugin to every target of that executor. Nx
295
+ lays the entry over what the plugin infers: its `dependsOn`, `inputs`,
296
+ `outputs` and `cache` replace the plugin's values, unless a list keeps them
297
+ with `"..."` ([[EVD-NX-TARGET-DEFAULTS]]).
298
+
299
+ An extra target that you define with a `targets` table in the Cargo metadata
300
+ ([Configuration](configuration.mara.md#changing-an-inferred-target)) gets the
301
+ entry in the same way, over what the table sets. The plugin checks only the
302
+ targets that it infers, so such an entry may turn on caching for the extra
303
+ target or replace its inputs.
304
+
305
+ `build` and `doc` run `@convesoft/nx-rust:cargo-outputs` from milestone 0.2
306
+ on, so that Nx batches and stores them apart from the tasks that wait for them
307
+ ([Batching and features](execution.mara.md#two-batches)); before, they ran
308
+ `@convesoft/nx-rust:cargo`. An entry keyed by `@convesoft/nx-rust:cargo` no
309
+ longer reaches them: where it is meant for them too, add the same entry keyed
310
+ by `@convesoft/nx-rust:cargo-outputs`. A repository that `nx add` set up before
311
+ has no entry keyed by `@convesoft/nx-rust:cargo-outputs`, so an entry keyed
312
+ `build` reaches the Rust `build` targets again, and the check below reports
313
+ what it changes; an entry such as `"build": { "dependsOn": ["^build"] }`
314
+ replaces their `dependsOn` and stops graph creation. Run
315
+ `nx g @convesoft/nx-rust:init`, which adds the missing entry and changes
316
+ nothing else, or add `"@convesoft/nx-rust:cargo-outputs": {}` yourself.
317
+
318
+ `nx add` adds `"@convesoft/nx-rust:cargo": {}`,
319
+ `"@convesoft/nx-rust:cargo-outputs": {}`, `"@convesoft/nx-rust:run": {}`,
320
+ `"@convesoft/nx-rust:lockfile": {}` and
321
+ `"@convesoft/nx-rust:release-publish": {}` where `targetDefaults` lacks them
322
+ ([Setup](setup.mara.md#adding-the-plugin)). Nx chooses an entry keyed by a
323
+ target's executor before one keyed by its name or a glob, so with these entries
324
+ in place only an entry keyed by one of the five executors reaches Rust
325
+ targets. The plugin checks its targets when Nx creates
326
+ the project graph, and `nx add` checks them before it writes anything
327
+ ([[DES-TARGET-DEFAULT-GUARD]]):
328
+
329
+ | What the entry does to a Rust target | Report |
330
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
331
+ | Turns on caching that the plugin leaves off | Error |
332
+ | Replaces the `inputs` or `outputs` that the plugin declares | Error |
333
+ | Replaces its `dependsOn`, which loses the dependency on `lockfile` or `hakari-check` or, on a `test` that waits for its crate's `build`, on that `build` | Error |
334
+ | Adds a dependency on tasks of other projects, such as `^build` | Warning |
335
+
336
+ Caching counts only on a target that the plugin leaves uncached: `fmt`, `bench`,
337
+ `run`, `audit`, `deny` and `update`, and `build` and `doc` where
338
+ [Caching](caching.mara.md#what-is-stored) says they run uncached, such as
339
+ in a workspace whose artifact directory lies outside the repository, and a
340
+ target whose table in the Cargo metadata sets `cache = false`. Turning on
341
+ caching for a target that the plugin caches changes nothing and is not
342
+ reported. A `project.json` or `package.json` in a crate's folder that turns on
343
+ caching for an uncached target is not reported here either; its task fails
344
+ before cargo runs and says why the plugin leaves the target uncached.
345
+
346
+ An error stops every Nx command that needs the project graph until the entry is
347
+ narrowed: Nx would otherwise restore results that the task would not produce,
348
+ or `nx affected` would miss crates. A warning is printed, and the graph is
349
+ created ([Setup](setup.mara.md#error-messages-and-warnings) says where you see
350
+ it). Each task of a target that the entry changes prints the warning again at
351
+ its start, also when Nx restores the task from the cache, and adding or
352
+ removing the entry runs those tasks again. The message names the entry, the
353
+ targets, the projects and the fixes that fit:
354
+
355
+ ```text
356
+ The targetDefaults entry "build" in nx.json changes targets that nx-rust infers:
357
+ - It replaces the inputs that nx-rust declares for "build", so that the cache key and nx affected miss files or settings that the task depends on. In api (rust/crates/api/Cargo.toml).
358
+ To narrow the entry (https://github.com/convesoft/nx-rust/blob/main/nx-rust/docs/targets.mara.md#target-defaults-that-reach-rust-targets), do one of these:
359
+ - Give the entry a "filter" that leaves these projects out, ...
360
+ - Add an empty entry keyed by the executor of these targets, "@convesoft/nx-rust:cargo-outputs": {}. ...
361
+ - Keep what nx-rust declares by putting "..." into the entry's "inputs" list, as in ["...", <your entries>].
362
+ ```
363
+
364
+ Where something else changes a Rust target as well, such as another plugin
365
+ listed in `nx.json`, nx-rust may not be able to tell which configuration made
366
+ the change. For caching turned on, or dependencies added, it then reports no
367
+ entry, but warns, naming the target and the fields that differ, and points to
368
+ `nx show target <project>:<target> --json`, whose `sourceMap` names the file
369
+ and entry behind each field. The tasks of that target print this warning at
370
+ their start too. For inputs, outputs or dependencies taken away, see
371
+ [Other plugins that reach Rust targets](#other-plugins-that-reach-rust-targets).
372
+
373
+ Neither the plugin nor `nx add` changes an entry that is there. Narrow it in one
374
+ of these ways:
375
+
376
+ - Give it a `filter`, which needs the entry written as a list. This one assumes
377
+ that your crates carry the tag `lang:rust`, for example through
378
+ `[workspace.metadata.nx]`. A filter on `executor`, naming the executor of
379
+ your JS targets, works as well.
380
+
381
+ ```json
382
+ {
383
+ "targetDefaults": {
384
+ "build": [
385
+ {
386
+ "filter": { "projects": ["!tag:lang:rust"] },
387
+ "dependsOn": ["^build"],
388
+ "cache": true
389
+ }
390
+ ]
391
+ }
392
+ }
393
+ ```
394
+
395
+ - Add an empty entry keyed by the executor of the Rust targets,
396
+ `"@convesoft/nx-rust:cargo": {}`, `"@convesoft/nx-rust:cargo-outputs": {}`
397
+ for `build` and `doc`, `"@convesoft/nx-rust:run": {}` for `run`,
398
+ `"@convesoft/nx-rust:lockfile": {}` for `lockfile` and
399
+ `"@convesoft/nx-rust:release-publish": {}` for `nx-release-publish`, as
400
+ `nx add` does where they are missing. Nx chooses an entry keyed by a
401
+ target's executor before one keyed by its name, so no entry keyed by a target
402
+ name reaches those targets.
403
+ - Where the entry is keyed by one of those executors, remove the field that the
404
+ message names.
405
+ - Where the entry replaces a list, keep the plugin's values with `"..."`, as in
406
+ `"inputs": ["...", "{workspaceRoot}/.tool-versions"]`.
407
+
408
+ ## Other plugins that reach Rust targets
409
+
410
+ Nx merges the targets of the plugins listed after nx-rust in `nx.json` over the
411
+ Rust targets, and then the `project.json` and `package.json` in the crate's
412
+ folder. Another plugin may add to a Rust target, but it may not take away an
413
+ `inputs`, `outputs` or `dependsOn` entry that nx-rust declares, or narrow one:
414
+ a negated pattern such as `"!{projectRoot}/src/**/*"`, or a `default` or other
415
+ named input that it defines anew for the crate, takes files out of the key just
416
+ as well. Nx could then restore a result that the task would not give, so graph
417
+ creation fails, also where `targetDefaults` is empty, with a message that names
418
+ the target, what was lost or left out and the plugins listed after nx-rust.
419
+ Keep that plugin away from the crate with an `exclude` on its entry in
420
+ `nx.json`, or, where the plugin is yours, have it keep nx-rust's entries with
421
+ `"..."` and add no negated pattern or named input for the crate. If the change
422
+ is what you want, write it into the `project.json` in the crate's folder: nx-rust takes
423
+ that file, and a `package.json` there, as your own statement for the project.
424
+ A plugin that gives a target an executor or command of its own, as Nx's Jest
425
+ plugin gives `test`, replaces the whole target, which then no longer runs
426
+ cargo, and nx-rust leaves it alone. Caching that another plugin turns on makes
427
+ the target's tasks fail before cargo runs.
428
+
429
+ nx-rust reads these lists as Nx's JavaScript helpers expand them, which comes
430
+ close to, but is not exactly, how Nx plans a task's key. It can refuse a
431
+ negated pattern that leaves the key as it was, such as one under
432
+ `{workspaceRoot}`, which the fixes above get past, and it misses a few rare
433
+ forms of narrowing, such as a named input that another plugin defines anew
434
+ for a crate that a `^` input reads
435
+ ([Risks](decisions.mara.md#risks)).
436
+
437
+ ## Options that cargo does not use
438
+
439
+ The `options` of a target default reach Rust targets too, and so do flags on
440
+ the command line, which Nx passes to every task of the targets it runs. A Rust
441
+ task runs as if an option it does not know were absent, such as Jest's
442
+ `passWithNoTests` or `--coverage`, and its output says so in one line per option
443
+ ([[REQ-UNKNOWN-OPTIONS]]):
444
+
445
+ ```text
446
+ api:test: ignoring option `coverage`, passed on the command line. Remove it, or check its spelling.
447
+ api:test: ignoring option `passWithNoTests`, which the cargo executor does not know. It comes from the workspace's configuration: run `nx show target api:test --json` and look under `sourceMap` for the file and entry. If it is a `targetDefaults` entry in nx.json, add a `filter` to it or add an empty entry keyed by "@convesoft/nx-rust:cargo".
448
+ ```
449
+
450
+ Such an option fails no task. The same goes for an option of the plugin that
451
+ the target does not take, such as `--targetTriple` on `test`, which runs on the
452
+ host triple only, or `--allTargets` on `build`, and for words after `--` on any
453
+ target but `run`, which Nx hands the task as positional arguments:
454
+
455
+ ```text
456
+ api:test: ignoring option `targetTriple`, which this target does not take, passed on the command line. Remove it.
457
+ api:test: ignoring the positional arguments ["3000"] (option `_`), passed on the command line. Remove them.
458
+ ```
459
+
460
+ A line says that an option was passed on the command line only where that is
461
+ certain: for a flag you typed, also after `--`, and on a dependency that a
462
+ `dependsOn` entry with `params: "forward"` reaches. Any other line names the
463
+ workspace's configuration, also for an option that a dependency gets through
464
+ `options: "forward"`. On `run`, the arguments after `--` go to the binary
465
+ instead: see [Running binaries](#running-binaries). There the line for an
466
+ option that `run` does not know, or for words typed without `--`, adds that you
467
+ can pass them to the binary after `--` or with `--args`. No other target passes
468
+ arguments on, and the plugin has no option for arguments of a test binary.
469
+
470
+ To keep a target default away from Rust targets, and so silence the warning,
471
+ narrow the entry with a `filter`. This one assumes that your crates carry the
472
+ tag `lang:rust`, for example through `[workspace.metadata.nx]`:
473
+
474
+ ```json
475
+ {
476
+ "targetDefaults": {
477
+ "test": [
478
+ {
479
+ "filter": { "projects": ["!tag:lang:rust"] },
480
+ "options": { "passWithNoTests": true }
481
+ }
482
+ ]
483
+ }
484
+ }
485
+ ```
486
+
487
+ Or add an empty entry keyed by the target's executor, the `executor` that
488
+ `nx show project <crate> --json` shows for it: `@convesoft/nx-rust:cargo`,
489
+ `@convesoft/nx-rust:cargo-outputs` for `build`, `napi-build`, `wasm-build` and `doc`,
490
+ `@convesoft/nx-rust:run` for `run`, `@convesoft/nx-rust:lockfile` for
491
+ `lockfile`, or `@convesoft/nx-rust:release-publish` for `nx-release-publish`.
492
+ `nx add` adds all five where they are missing.
493
+ Nx prefers an entry keyed by the executor to one keyed by the target name, so
494
+ then no entry keyed by a target name reaches the targets of that executor.
495
+
496
+ A Rust option with a value of the wrong type, such as a number for `profile`,
497
+ is not ignored: Nx rejects it before the plugin sees it. Rust tasks normally run
498
+ in a batch, and then every task of that batch fails, with a message that does
499
+ not name the option. A single task, such as `run` or any task with
500
+ `--batch=false`, fails alone, and Nx's message names the option.
501
+
502
+ ## Formatting
503
+
504
+ `nx format:check` and `nx format:write` are Nx's own commands, not targets.
505
+ They run prettier or oxfmt over files and never run rustfmt, so they leave Rust
506
+ sources alone ([[EVD-NX-FORMAT]]). Rust formatting is the `fmt-check` and `fmt`
507
+ targets, which keep Cargo's names so that they are not taken for that command:
508
+
509
+ ```sh
510
+ nx format:check # JS, TS, Markdown, JSON
511
+ nx affected -t lint test build fmt-check # plus rustfmt for the affected crates
512
+ nx affected -t fmt # rustfmt rewrites the affected crates
513
+ ```
514
+
515
+ Both targets exist on every crate and touch only the crates they run for. A
516
+ path dependency outside the workspace, or a member that Nx leaves out such as an
517
+ excluded vendored crate, is never reformatted. `cargo fmt --all` would reformat
518
+ the former ([[EVD-CARGO-TARGET-COMMANDS]]). Neither target passes `--locked`,
519
+ not even in locked mode: `cargo fmt` reads no lockfile and rejects the flag.
520
+
521
+ If your workspace formatter is oxfmt, `nx format:write` also formats
522
+ `Cargo.toml` files, because oxfmt formats TOML.
523
+
524
+ ## Requirements
525
+
526
+ :::mara requirement REQ-INFERRED-TARGETS
527
+ :mid: 01M78FHG7FQ71E32Q38CHFFHB0
528
+ :title: Infer targets from the shape of the crate
529
+ :status: accepted
530
+ :satisfies: NEED-ZERO-CONFIG
531
+
532
+ Each crate's Nx targets are derived from Cargo's description of the crate, without per-crate declarations. The kinds of Cargo targets a crate has decide whether it gets `run`, `bench` and the targets for other target triples. A crate with `publish = false` gets no release targets. These are the targets the plugin infers: where the crate's folder also is a JS project, Nx lays the folder's `package.json` and `project.json`, and the plugins listed after this one, over them, and a script or target of one of their names replaces the inferred target or merges into it ([[REQ-MIXED-PROJECTS]]).
533
+ :::
534
+
535
+ :::mara requirement REQ-NO-RUST-TASK-DEPS
536
+ :mid: 01M78FHG7FGDP772BSP1FSAYKN
537
+ :title: Declare no task dependencies between Rust crates
538
+ :status: accepted
539
+ :satisfies: NEED-EFFICIENT-BUILDS
540
+
541
+ No inferred target of a Rust crate depends on a target of another Rust crate, with three exceptions. Two are targets of the workspace project, which is the root crate's project where the root manifest is a package: every cached target of a crate other than `fmt-check` depends on the lockfile task of its workspace ([[DES-LOCKFILE-HASHING]]), and, in a workspace that uses the `hakari` feature strategy, on the workspace's drift check of the hack crate, which depends only on the lockfile task ([[DES-UNIFICATION]]). The third orders tasks that write the same files: under `workspace-build`, a crate's `test` depends on the `build` of each crate of its workspace whose executables a `cargo test` of the whole workspace replaces ([[ADR-WORKSPACE-TEST-EXECUTABLES]], [[DES-TARGETS]]). A change in a dependency reaches the dependent through cache inputs, not through task ordering. A dependency between two targets of the same crate is no dependency between crates: a crate's `test` depends on the crate's own `build` where `cargo test` replaces the executables of that `build`, which under `workspace-build` is one case of the third exception ([[DES-TARGETS]]). The plugin adds no task dependency to JS projects either. A `^build` that a JS target declares itself reaches the `build` of the crates its project depends on directly, as Nx defines `^build`, and goes no further where that `build` is the plugin's. Where a script, a `project.json` target or another plugin replaced the `build` of a crate whose folder also is a JS project, that target is not inferred: the plugin adds nothing to it and removes nothing from it, and a `^build` of its own reaches the `build` of the crates that its project depends on directly ([[REQ-MIXED-PROJECTS]]).
542
+ :::
543
+
544
+ :::mara requirement REQ-TARGET-DEFAULT-GUARD
545
+ :mid: 01M78FHG7FV5M1E44R30RRAB5P
546
+ :title: Report target defaults that change Rust targets
547
+ :status: accepted
548
+ :satisfies: NEED-CLEAR-FAILURES
549
+ :satisfies: NEED-CORRECT-CACHE
550
+ :mitigates: RISK-TARGET-DEFAULTS
551
+
552
+ When a `targetDefaults` entry in `nx.json` adds a dependency on other crates' targets to an inferred Rust target, replaces the inputs or outputs the plugin inferred for it, or turns on caching that the plugin left off, the plugin reports the entry and the affected target and says how to narrow the entry. A list that keeps the inferred values with `"..."` does not count as replacing them.
553
+ :::
554
+
555
+ :::mara requirement REQ-RUN-WATCH
556
+ :mid: 01M78FHG7FQ0KY79YN7KV80X58
557
+ :title: Run binaries as continuous tasks
558
+ :status: retired
559
+ :satisfies: NEED-UNIFORM-COMMANDS
560
+
561
+ A crate's `run` target can serve as a continuous Nx task that other targets depend on, and can restart when its sources change.
562
+
563
+ Retired on 13 November 2026: not part of v1. `run` is not continuous by default, because a continuous task that exits while a dependent runs fails the Nx command, and many binaries are one-shot tools that other targets wait for ([[EVD-NX-24-TARGETS]]). A crate that serves something makes its `run` continuous, with a `readyWhen` check, in `[package.metadata.nx.targets.run]`, which [[DES-METADATA-TABLES]] already allows. Restarting on change would need a file watcher in the executor or a tool the user installs; `nx watch` waits for its command to exit and cannot restart one that keeps running.
564
+ :::
565
+
566
+ ## Design
567
+
568
+ :::mara design DES-TARGETS
569
+ :mid: 01M78FHG7FMRNFBSN2G9VG7CX3
570
+ :title: Inferred targets
571
+ :status: accepted
572
+ :satisfies: REQ-INFERRED-TARGETS
573
+ :satisfies: REQ-TARGET-NAMES
574
+ :satisfies: REQ-NO-RUST-TASK-DEPS
575
+
576
+ | Default name | Cargo's or the tool's name | Exists on | Cached | Nx outputs |
577
+ | -------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------- |
578
+ | `build` | `build` | Every crate | Yes | Final artifacts only ([[DES-OUTPUTS]]) |
579
+ | `check` | `check` | Every crate | Yes | None |
580
+ | `lint` | `clippy` | Every crate | Yes | None |
581
+ | `test` | `test` | Every crate | Yes | None |
582
+ | `fmt-check` | `fmt --check` | Every crate | Yes | None |
583
+ | `fmt` | `fmt` | Every crate | No | None |
584
+ | `bench` | `bench` | Crates with a bench target | No | None |
585
+ | `run` | `run` | Crates with a binary target | No | None |
586
+ | `napi-build`, `wasm-build` | none | Crates that produce that artifact | Yes | [[DES-ARTIFACT-STEPS]] |
587
+ | `nx-release-publish` | `publish` | Crates without `publish = false`, other than the [[TERM-HACK-CRATE]] | No | None |
588
+ | `doc` | `doc` | The workspace project | Yes | The workspace's doc folder ([[DES-OUTPUTS]]) |
589
+ | `lockfile` | `update --workspace` | The workspace project | No | The crates' digests ([[DES-LOCKFILE-HASHING]]) |
590
+ | `hakari-check` | cargo-hakari's `generate --diff` and `manage-deps --dry-run` | The workspace project, where the workspace uses the `hakari` strategy of [[DES-UNIFICATION]] | No | None |
591
+ | `audit` | cargo-audit's `audit` | The workspace project | No | None |
592
+ | `deny` | cargo-deny's `check` | The workspace project, where a cargo-deny configuration exists | No | None |
593
+ | `update` | `update` | The workspace project | No | None |
594
+ | `coverage-baseline` | cargo-affected's `collect` | The workspace project, where the workspace turns on `affectedTests` ([[DES-BASELINE]]) | No | None |
595
+
596
+ Only `clippy` is renamed, to `lint`: `lint`, `test` and `build` are the target names that Nx projects share. Formatting keeps Cargo's names, `fmt-check` and `fmt`, because Nx's `format` is a built-in command and not a target, and the targets of the workspace project keep the names of Cargo and the tools ([[ADR-NX-TARGET-NAMES]]); the lockfile task is called `lockfile`, and the drift check of the hack crate `hakari-check`, after `fmt-check`, because it checks without changing anything. Every name can be changed through plugin options, the names of the artifact targets and of the workspace project's targets included, apart from `nx-release-publish`: Nx release runs the target only under that name ([[DES-RELEASE]]). `bench` is not cached, because timings differ between runs. The commands are [[DES-TARGET-COMMANDS]] and [[DES-WORKSPACE-TARGETS]].
597
+
598
+ Targets come from the `cargo metadata` report ([[DES-METADATA-REPORT]]): `run` exists when the crate has a binary target, `bench` when it has a bench target, an [[TERM-ARTIFACT-TARGET]] when the crate produces that artifact ([[DES-ARTIFACT-STEPS]]), and `nx-release-publish` unless the manifest sets `publish = false` or the crate is the hack crate of a cargo-hakari configuration ([[DES-RELEASE]]). The last seven rows are targets of the [[TERM-WORKSPACE-PROJECT]]; `deny` exists only where a cargo-deny configuration file is in the workspace root, `hakari-check` only where the workspace uses the `hakari` strategy, which its files decide ([[DES-UNIFICATION]]), and `coverage-baseline` only where the workspace turns on `affectedTests` ([[DES-BASELINE]]). Whether a tool is installed never decides whether a target exists.
599
+
600
+ **Executors.** Every inferred target runs the plugin's cargo executor, `@convesoft/nx-rust:cargo`, which has the batch implementation of [[DES-BATCH]], apart from `build`, `napi-build`, `wasm-build` and `doc`, the targets whose files Nx stores ([[DES-OUTPUTS]]), which run `@convesoft/nx-rust:cargo-outputs`, the same executor with the same batch implementation under a name of its own, so that Nx batches and stores them apart from the tasks that wait for them ([[DES-BATCH]]); `run`, which runs `@convesoft/nx-rust:run`, and `lockfile`, `hakari-check` and `coverage-baseline`, which run `@convesoft/nx-rust:lockfile`, two executors without a batch implementation ([[DES-TARGET-COMMANDS]], [[DES-LOCKFILE-HASHING]], [[DES-UNIFICATION]], [[DES-BASELINE]]); and `nx-release-publish`, which runs `@convesoft/nx-rust:release-publish`, an executor with a batch implementation of its own ([[DES-RELEASE]]). The lockfile executor runs the command of the target's default name, so that the empty entry that `init` adds for it in `targetDefaults` covers `hakari-check` and `coverage-baseline` as well ([[DES-TARGET-DEFAULT-GUARD]]). Each target carries its default name from the table in its metadata, as `metadata.cargo.target`, so that the executor runs the same command whatever name `targetNames` gives the target. It also carries the `locked` option of the plugin entry that created its project, as `metadata.cargo.locked`, from which the executor decides locked mode ([[DES-INVOCATION]]). A target that names one of these executors but that the plugin did not infer has no such name, and its task fails before cargo runs ([[DES-DIAGNOSTICS]]).
601
+
602
+ No inferred target has a `dependsOn` entry that names another Rust crate's target, except that every cached crate target other than `fmt-check` depends on the lockfile task of its workspace and, under `hakari`, on its `hakari-check`, and that `test` depends on the `build` of the crates that the rule below names ([[REQ-NO-RUST-TASK-DEPS]]); none uses `^build` ([[ADR-NO-RUST-BUILD-DEPS]]). Dependencies reach a target through `^` inputs ([[DES-INPUTS]]). The plugin adds no `dependsOn` entry to a JS project. A JS target's own `^build` reaches the `build` of the crates its project depends on directly, which is how Nx defines `^build`, and ends there where those are the plugin's targets. A `build` that replaced the plugin's in a crate whose folder also is a JS project brings its own `dependsOn`, which may hold `^build` in turn ([[DES-MIXED-PROJECTS]]).
603
+
604
+ **`test` after `build`.** Where `cargo test` replaces the executables that a crate's `build` declares ([[DES-OUTPUTS]]), the crate's `test` depends on the crate's own `build`, as `{ "target": <name> }` after its dependencies on tasks of the workspace project, under the names that `targetNames` gives the two, and whether or not either is cached ([[ADR-TEST-AFTER-BUILD]]). Under `workspace-build`, whose `test` steps select the whole workspace and so replace the executables of every crate of the workspace for which the rule holds, a crate's `test` also depends on the `build` of each other member with a project for which it holds, as one entry `{ "projects": ["directory:<root>", …], "target": <name> }` that names each by its root, as the dependency on the lockfile task does, so that the entry holds whatever a `package.json` or `project.json` names the project ([[ADR-WORKSPACE-TEST-EXECUTABLES]]); every workspace uses `workspace-build` until the other strategies exist (nxr-k64tm5), under which a `test` selects its crate alone and depends on its own `build` only. The rule reads the crate's `cargo metadata --no-deps` report: the crate has a target of kind `bin`, and a target of kind `test`, whatever its `test` flag, or of kind `bench` whose `test` flag is on, whatever the `required-features` of either. That is an integration test with or without a harness, or a bench that `cargo test` runs. A `[[test]]` with `test = false` counts because the `test` option of `test`, which the command line can give where graph creation never sees it, makes cargo build the crate's binaries for it and run it, replacing the executables as for any integration test, while a plain `cargo test` leaves them alone ([[DES-TEST-RUN]], "One test target"; [[EVD-CARGO-TEST-TARGET-SELECTOR]]); a crate counted for it whose `test` never takes the option only orders two tasks. The control plane decided this in nxr-k5y74e on 22 November 2026, after the review of the option found that a restored `build` of such a crate was replaced under its key, from [[GOAL-TRUSTED-CACHE]]; to undo it, leave such a target out again and accept that a selected run of it can replace a restored executable. An example, also one with `test = true`, unit tests, doctests and a bench without `test` make cargo build no binary for the test run, and `cdylib` and `staticlib` files are never replaced. A binary or test whose required features are off makes cargo build none either, but whether they are on depends on the run, and a crate counted without need only orders two tasks; a `test` flag that the report lacks counts as on ([[EVD-CARGO-ARTIFACT-WRITERS]]). The target carries `metadata.cargo.waitsForBuild` where it depends on its own `build`, and `metadata.cargo.waitsForBuilds`, the roots of every crate whose `build` it depends on, for the executor. Nx gives the dependency the configuration of the command where `build` has it and the default configuration of `build` otherwise, so the `build` that `test` waits for is the one that the same command names. With `--exclude-task-dependencies` Nx keeps the edge where the command names both targets, and runs `test` alone where it names `test` alone. A cache hit of `test` still waits for `build` to run or be restored. The rule does not depend on the runner of `test`: nextest builds the test executables through cargo and runs them after cargo has exited, as `cargo test` does (reasoned, not tried). `bench` needs no such dependency: Nx starts a task with `parallelism: false` only when no other task runs, and none while it runs ([[DES-TARGET-COMMANDS]]). `run` has none either ([[DES-OUTPUTS]]).
605
+
606
+ **Guard.** Before cargo runs, the executor fails a `test` task where the task graph holds a task of the `build`, by the name in its metadata, of a project whose root its `waitsForBuilds` names, or of its own project where a graph from before that list carries only `waitsForBuild`, that Nx neither finishes before the `test` starts nor starts only after the `test` has finished, as where a `project.json`, a `package.json`, a target table or a `targetDefaults` entry replaces the `dependsOn` of `test` without `"..."`. Nx starts a task once its ordinary dependencies have completed, which is after their outputs are stored, and once its continuous dependencies have started, or reported ready where the edge waits for that, and it starts a continuous task only once that task's own ordinary dependencies have completed ([[EVD-CARGO-ARTIFACT-WRITERS]]). So the graph orders the two where a path of dependencies leads from one to the other, through ordinary and continuous dependencies alike, whose last edge, the one into the task that comes first, is an ordinary dependency: a `test` that depends on a continuous helper which depends on `build` passes. A path that reaches `build` only as a continuous dependency guarantees no more than that `build` has started, and does not count; Nx records every edge into a continuous task as such, so a `build` that is itself continuous never counts as finished. The message names both tasks, what could go wrong and the fix ([[DES-DIAGNOSTICS]]). A command whose graph holds no such `build`, such as `nx test <crate>` once the dependency is gone, has nothing to order and passes. A task invoked outside a task graph that holds it is not checked. [[DES-TARGET-DEFAULT-GUARD]] reports a `targetDefaults` entry that drops the dependency when the graph is created.
607
+ :::
608
+
609
+ :::mara design DES-TARGET-COMMANDS
610
+ :mid: 01M78FHG7F9X4M34PB2MP9Y7S8
611
+ :title: Commands of the remaining per-crate targets
612
+ :status: accepted
613
+ :satisfies: REQ-INFERRED-TARGETS
614
+ :satisfies: REQ-CARGO-UNCHANGED
615
+
616
+ | Target | Command | Cached | Batched |
617
+ | ----------- | --------------------------------------- | ------ | ----------------------------- |
618
+ | `check` | `cargo check --all-targets -p <crate>` | Yes | Yes |
619
+ | `lint` | `cargo clippy --all-targets -p <crate>` | Yes | Yes |
620
+ | `fmt-check` | `cargo fmt --check -p <crate>` | Yes | Yes |
621
+ | `fmt` | `cargo fmt -p <crate>` | No | Yes |
622
+ | `bench` | `cargo bench -p <crate>` | No | No: `parallelism` is `false` |
623
+ | `run` | `cargo run -p <crate>` | No | No: an executor without batch |
624
+
625
+ Each command starts in the root folder of the crate's workspace, names the crate, `<crate>` in the table, by its package ID specification and passes `--locked` as the `locked` option says ([[DES-INVOCATION]]), except `fmt` and `fmt-check`, which name it by its package name: `cargo fmt` resolves no dependencies, takes no specification and rejects the flag ([[EVD-CARGO-TARGET-COMMANDS]], [[EVD-CARGO-PACKAGE-SPECS]]). Batched tasks share cargo calls as [[DES-BATCH]] groups them; `cargo fmt` takes several `-p` as the cargo commands do.
626
+
627
+ **Flags as options.** A flag beyond the package selection comes from an option of the target, so that a command passes only what its options ask for ([[DES-INVOCATION]]). `--all-targets` on `check` and `lint` is such an option, on by default. A crate switches it off in the options of the target in its `[package.metadata.nx]` table ([[DES-METADATA-TABLES]]), for example when its benches need a nightly compiler, which stable rejects under `--all-targets`. Tasks whose options differ never share a cargo call ([[TERM-GROUP]]). The option is `allTargets` ([[DES-PLUGIN-OPTIONS]]). `--all-targets` is what rust-analyzer passes by default, so `check` compiles the units the editor compiles and the two reuse each other's work ([[EVD-CARGO-TARGET-COMMANDS]]).
628
+
629
+ **Warnings.** No target adds a flag that turns warnings into errors. A task fails on warnings where the repository says so through Cargo: lint levels in `[lints]` and `[workspace.lints]`, `build.warnings` in `.cargo/config.toml` or `CARGO_BUILD_WARNINGS`, which Cargo honours from 1.97 on, and `RUSTFLAGS`, all of which are cache inputs ([[DES-INPUTS]]). Cargo ignores `build.warnings` under `--message-format=json`, which the JSON compile steps of the batch pass, so the batch applies it to their result itself, failing every task of such a step that passed where its messages report a warning ([[DES-BATCH]], "Denied warnings"). Passing `-D warnings` to clippy would differ from plain `cargo clippy` and check every selected member again whenever a developer alternates the two ([[EVD-CARGO-TARGET-COMMANDS]]).
630
+
631
+ **Formatting.** `fmt` exists on every crate and formats only the crates of its tasks. `cargo fmt --all` would also rewrite path dependencies outside the workspace, and plain `cargo fmt` in the workspace root would rewrite members that have no project ([[EVD-CARGO-TARGET-COMMANDS]], [[REQ-SKIP-CRATES]]). `cargo fmt -p` takes package names only, not package ID specifications, and matches them against the workspace's members alone, whose names are unique, so the name addresses the crate also where a dependency has the same name ([[EVD-CARGO-PACKAGE-SPECS]]).
632
+
633
+ **bench.** The target has `parallelism: false`, so that Nx starts no other task while benchmarks run. Nx never puts such a task into a batch, so each `bench` task is a cargo call of its own ([[EVD-NX-24-TARGETS]]). So `cargo bench`, which replaces the executables of a `build` in the release profile, never runs beside a `build`, and `bench` needs no dependency on it. Once tasks run in batches ([[DES-BATCH]]), a batch could start beside a running `bench` only after the readiness verdict of a continuous task, which an inferred target never waits for ([[EVD-CARGO-ARTIFACT-WRITERS]]).
634
+
635
+ **run.** One `run` target per crate. When the crate has several binaries, an option of the target, `bin`, passes `--bin`; it is set on the command line or in the crate's metadata ([[DES-PLUGIN-OPTIONS]]). Without it and without `default-run` in the manifest, cargo fails and lists the binaries. The `args` option, a string, gives the binary its arguments. It is split into words at blanks outside quotes. Single quotes, double quotes and backslashes quote and escape as in a POSIX shell, an empty pair of quotes is an empty word, and nothing is expanded or treated as an operator, so `|`, `;` and `>` are ordinary characters. An unterminated quote, or a backslash at the end, fails the task with a message that names the option. Arguments after `--` on the `nx` command line go to the binary too, after those of `args`, within two limits that come from Nx ([[EVD-NX-OPTION-VALIDATION]]). When the command has `--`, Nx drops the flags before it that Nx does not know itself, so `--bin` and `--args` cannot be combined with `--`. Nx also parses what follows `--` as options of the target and checks them against its schema before the executor runs, so an argument with the name of one of `run`'s options can be rejected. `--args` works in both cases. Nx also reads a value of `--args` that looks like a number as a number, so `--args=3000` and `--args="3000"` fail the schema. `--args=" 3000"`, with a blank, stays a string and gives the one word `3000`, and `-- 3000` passes `3000` as well. `run` uses an executor that has no batch implementation, because `cargo run` accepts one package only, while Nx hands every task of an executor with a batch implementation and `preferBatch` to one batch, also the tasks of `nx run-many -t run` ([[EVD-CARGO-TARGET-COMMANDS]], [[EVD-NX-24-TARGETS]]). `run` is not ordered after `build`: where its options differ from those of `build`, its executable replaces the one of `build` in the artifact directory ([[DES-OUTPUTS]], [[RISK-ARTIFACT-DIR-WRITERS]]). `run` is not a continuous task: a task that depends on it waits until the binary exits. A crate that serves something sets `continuous` and `readyWhen` on its `run` in its metadata ([[DES-METADATA-TABLES]]). `nx run <project>` is Nx's own syntax and needs a target, so the short form is `nx run <project>:run`.
636
+
637
+ The targets of the workspace project are [[DES-WORKSPACE-TARGETS]].
638
+ :::
639
+
640
+ :::mara design DES-WORKSPACE-TARGETS
641
+ :mid: 01M78FHG7FDHZMAH480DED8M6W
642
+ :title: Targets of the workspace project
643
+ :status: accepted
644
+ :satisfies: REQ-WORKSPACE-PROJECT
645
+
646
+ The [[TERM-WORKSPACE-PROJECT]] hosts the targets that concern a whole Cargo workspace. Each command starts in the workspace root ([[DES-INVOCATION]]).
647
+
648
+ | Target | Command | Exists | Cached | Inputs |
649
+ | ------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
650
+ | `doc` | `cargo doc --no-deps --workspace` | Always | Yes, as [[DES-OUTPUTS]] says | Those of every cached target ([[DES-INPUTS]]), with the files of every member through the project's dependencies |
651
+ | `audit` | `cargo audit` | Always | No | `Cargo.lock`, the root `Cargo.toml` and `.cargo/audit.toml` of the workspace root |
652
+ | `deny` | `cargo deny check` | Where `deny.toml`, `.deny.toml` or `.cargo/deny.toml` is in the workspace root | No | `Cargo.lock`, the root `Cargo.toml`, the cargo-deny configuration file and the manifest of every member |
653
+ | `update` | `cargo update` | Always | No | `Cargo.lock` and the root `Cargo.toml` |
654
+ | `lockfile` | `cargo update --workspace`, with `--locked` in locked mode, then a digest per crate | Always | No | `Cargo.lock`, read also when git ignores it, the root `Cargo.toml`, the `Cargo.toml` of every member and of every path package in the repository, and the workspace files of [[DES-INPUTS]] |
655
+ | `hakari-check` | `cargo hakari generate --diff`, then `cargo hakari manage-deps --dry-run` | Where the workspace uses the `hakari` strategy of [[DES-UNIFICATION]] | No | Those of `lockfile`, and the configuration file of cargo-hakari |
656
+ | `coverage-baseline` | `cargo affected status`, then `cargo affected collect`, with or without `--diff` | Where the workspace turns on `affectedTests` ([[DES-BASELINE]]) | No | The plugin's input only |
657
+
658
+ The coverage baseline target, `coverage-baseline`, is [[DES-BASELINE]]'s.
659
+
660
+ **doc.** The workspace is documented in one call and its documentation is one site. rustdoc writes a folder per documented crate and files that every run merges, such as the search index and the list of crates. The output is therefore the whole `doc` folder of the [[TERM-ARTIFACT-DIR]], and a cache hit restores what a run writes. Outputs per crate could not do that: Nx restores a folder output by replacing it, so overlapping folders would delete each other's pages, and a crate's own folder lacks the shared styles and search index ([[EVD-CARGO-TARGET-COMMANDS]], [[EVD-NX-24-TARGETS]]). `--no-deps` comes from an option of the target that is on by default, as the flags of [[DES-TARGET-COMMANDS]] do: `noDeps`, set like the other options of the workspace project's targets ([[DES-PLUGIN-OPTIONS]]).
661
+
662
+ **Existence.** Whether a tool is installed never decides whether a target exists. Every machine thus computes the same graph, and a missing tool cannot make `nx run-many -t audit` leave a workspace out without a word ([[ADR-CARGO-SOURCE-OF-TRUTH]], [[REQ-DIAGNOSTICS]]). A task whose tool is missing fails with the message of [[DES-DIAGNOSTICS]]. `deny` exists only where cargo-deny is configured, because without a configuration file cargo-deny falls back to defaults that reject every license ([[EVD-CARGO-AUDIT-DENY]]).
663
+
664
+ **lockfile.** The lockfile task is not cached and runs whenever a task that depends on it runs: every cached target of the workspace's crates other than `fmt-check`, and `doc` ([[DES-LOCKFILE-HASHING]]).
665
+
666
+ **hakari-check.** The drift check of the [[TERM-HACK-CRATE]] exists only on a workspace that uses the `hakari` strategy, because only there do the crates' keys rely on the hack crate. It is not cached, depends on the lockfile task, and runs whenever a task that depends on it runs: the same tasks as for the lockfile task. When it fails, none of them runs. [[DES-UNIFICATION]] ("Drift") says what it checks and why; its inputs, like the lockfile task's, only decide what `nx affected` selects.
667
+
668
+ **Caching.** `audit`, `deny` and `update` are not cached. cargo-audit and cargo-deny fetch the RustSec advisory database when they run, and no input covers it, so a cached pass could hide an advisory published since ([[EVD-CARGO-AUDIT-DENY]]). `update` exists to change `Cargo.lock`. Their inputs are declared all the same, so that `nx affected` selects them when a file they read changes. They and `lockfile` also have the plugin input of [[DES-INPUTS]], so that a change to the JS lockfile outside the plugin's package does not select them.
669
+
670
+ **Locked mode.** `update` never passes `--locked`, also with the `locked` option or `NX_RUST_LOCKED=true`: `cargo update --locked` fails whenever the lockfile would change ([[EVD-CARGO-TARGET-COMMANDS]]), and changing it is what the task is for ([[REQ-NO-MANIFEST-WRITES]]). `deny` passes `--locked` to cargo-deny in locked mode and then fails instead of updating `Cargo.lock`; without it, cargo-deny resolves the workspace as plain cargo would and may update the lockfile. cargo-audit only reads `Cargo.lock` and has no such flag ([[EVD-CARGO-AUDIT-DENY]]).
671
+ :::
672
+
673
+ :::mara design DES-TARGET-DEFAULT-GUARD
674
+ :mid: 01M7AT4GDP59EWQTMVSVR69G4M
675
+ :title: Report target defaults that change inferred targets
676
+ :status: accepted
677
+ :satisfies: REQ-TARGET-DEFAULT-GUARD
678
+
679
+ **Where.** `createDependencies` receives the projects after Nx has laid the `targetDefaults` of `nx.json` over the plugin's targets, while the plugin entry that created them still holds what it inferred ([[EVD-NX-TARGET-DEFAULTS]]). `createNodes` hands Nx a copy of its projects, so that this holds also where Nx loads the plugin into its own process, where it rewrites the project names in the lists it receives in place ([[EVD-NX-24-PLUGIN-NODES]]). For each inferred target the plugin compares the two. A target whose executor is no longer the inferred one was replaced by another file and is left alone. An extra target that a `targets.<name>` table of the Cargo metadata defines is not compared either ([[DES-METADATA-TABLES]]): the plugin infers nothing for it, so nothing of the plugin's can be lost, and Nx lays `targetDefaults` over the table as over any target that a plugin infers, so that what an entry does to it is the repository's own statement about that target, as the table is. The plugin tells its inferred targets by the `cargo` record in their metadata, which the executor reads as well ([[DES-OUTPUTS]], "Per project"). Before, such a target was compared with its table as if the plugin had inferred it: `"e2e": { "cache": true }` failed graph creation for a crate whose table defines `e2e` with an executor, so did an entry that replaced the table's `inputs` or `outputs`, and caching that another plugin turned on drew the warning of **Which layer**, which nothing backed, as the task does not run the plugin's executor. `init` runs the same check through the plugin's `createDependencies`, on `nx.json` with the empty entries keyed by the plugin's executors that it adds where they are missing ([[DES-GENERATORS]]). In a repository set up that way, Nx lays no entry keyed by a target's name or a glob over the plugin's targets, so the check reports entries keyed by the plugin's executors there; it stays the check for repositories that were set up by hand or lost those entries later, and its message names the same fix.
680
+
681
+ **What counts.** Each row compares the target as Nx merged it with the target as the plugin inferred it.
682
+
683
+ | The merged target | Severity |
684
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
685
+ | Has caching on where the plugin's `cache` is not `true` | Error |
686
+ | Lacks an `inputs` entry that the plugin declared | Error |
687
+ | Lacks an `outputs` entry that the plugin declared | Error |
688
+ | Lacks a `dependsOn` entry that the plugin declared, such as the one on the workspace's lockfile task ([[DES-LOCKFILE-HASHING]]) or the one of `test` on the crate's own `build` ([[DES-TARGETS]]) | Error |
689
+ | Has a `dependsOn` entry that the plugin did not declare and that Nx's task graph resolves to tasks of other projects: `^<target>`, `dependencies: true`, or `projects` or `<project>:<target>` that name another project | Warning |
690
+
691
+ The differences are read from the targets that Nx merged, and from nothing else: a target that does not differ is not reported, whatever `targetDefaults` holds. A difference counts against an entry only where the plugin can tell that the entry made it (**Which layer**). The check runs whether `targetDefaults` holds entries or not; where it is empty, or no key of it can reach a target, by its executor, its name or a glob, no entry is blamed, and a difference is judged as **Other layers** says. The comparison is with what the plugin infers for the target at the time: where it declares no inputs, outputs or `dependsOn`, there is nothing to lose, and caching turned on counts only for a target that it leaves uncached in that project, by design, for a reason of [[DES-OUTPUTS]] such as an artifact directory outside the repository, or because a `targets.<name>` table of its Cargo metadata sets `cache = false`.
692
+
693
+ **Severity.** An entry that only adds dependencies costs time and leaves results correct ([[EVD-NXRUST-BUILD-DEPS]]), so it is a warning. The other rows let Nx restore a result that the task would not produce, or let `nx affected` miss a crate, so they are errors ([[GOAL-TRUSTED-CACHE]]). A `dependsOn` that loses the lockfile task drops the digests from its key ([[DES-LOCKFILE-HASHING]]), and one that loses the crate's `build` lets Nx run `test` beside it and store the executable of `cargo test` for `build` ([[DES-OUTPUTS]]).
694
+
695
+ **Which layer.** `createDependencies` receives no record of which layer set a value, so where a target differs, the plugin rebuilds it with Nx's own code. The layers are the plugin's projects as its `createNodes` returned them; the elements of `targetDefaults` that Nx's synthesis (`createTargetDefaultsResults` from `nx/src/devkit-internals`) lays over them, given what Nx's default plugins make of the `package.json` and `project.json` in the project's folder, the project's name and tags as Nx merged them, which are those that the synthesis reads, also where another plugin gave them, and the plugin that is the source of the target, which `filter.plugin` compares with; and those default-plugin results. That source is the plugin whose node first gave the target the executor that it has, because Nx keeps it when a later plugin gives the same executor, and graph creation cannot see which plugin that was. So the synthesis is run with the name under which Nx knows the plugin's entry as the source and, where `nx.json` lists a plugin other than this one, once more for each other plugin that an element's `filter.plugin` names and once for one that none names; an element that one of these runs lays over the target may apply to it, and one that none lays over it cannot. Each run gives a rebuild of its own. Each layer is merged with Nx's merge of project nodes, so `"..."` in lists and in objects, and the elements of an entry's list, behave as in Nx. Nx replaces each project reference in a target's `inputs` and `dependsOn` with the project that has that name when the plugin's projects are merged, and writes that project's final name in its place, so a `project.json` that renames a crate renames the references to it ([[EVD-NX-24-PLUGIN-NODES]]). The plugin gives the references that it declares the same names, in the inferred target and in its layer of the rebuild, where that is certain: a name that the plugin gave a project of its entry becomes the name under which the merged graph knows the project at that root. It renames only the forms that Nx renames: a `projects` string other than `*`, `self` and `dependencies` (`self` and `dependencies` in `inputs`), an element of a `projects` list that is no glob pattern, and a `<project>:<target>` string in `dependsOn` with exactly one colon that Nx can read no other way, because neither the string nor its first part is a target of the project itself and the string names no project. Every other name stays as written, so that a renaming that the plugin cannot prove stays a difference. Each of `cache`, `inputs`, `outputs` and `dependsOn` is then judged on its own, and a difference in one never decides another. Where a rebuild gives the field, and the project's name and tags, which filters read, as Nx merged them, a difference that the rebuild without the `targetDefaults` layer lacks is reported against the entry that this run of the synthesis laid over the target, with the severity below, and where the runs for several source plugins give the field, against the entry of each, since graph creation cannot tell which of them Nx made; a difference that the rebuild has without that layer was made by the folder's `project.json` or `package.json` and is not reported. The review of nxr-gyyhdj found that, with a plugin listed before this one that gave a crate's `check` its executor first, an entry keyed by the cargo executor and filtered to that plugin and an entry keyed `check` and filtered to the crate, which replaced the inputs in the same way, were reported as the entry keyed `check` alone, which the run with this plugin as the source lays over the target, while Nx, which tries the key of the target's executor first and falls through to that of its name only where no element of the first matches, had applied the entry keyed by the executor ([[EVD-NX-24-PLUGIN-NODES]]). Where none does, as when another plugin listed in `nx.json` contributes to the project or a reference was renamed in a way that the plugin cannot prove, an inferred `inputs`, `outputs` or `dependsOn` entry that the merged target lacks and that the rebuild without the `targetDefaults` layer keeps, and caching that is on where the plugin leaves the target uncached and the rebuild without that layer leaves it off, is still an error against each entry with an element that may apply to the target and would make it: one that sets that list without `"..."` in it, or `cache: true`, and not before an object-level `"..."`, where Nx keeps the value below. In the same way, a `dependsOn` entry that the merged target adds and the rebuild without the `targetDefaults` layer lacks is the warning against each entry with an element that may apply to the target and lists it, unless that list stands before an object-level `"..."` where the plugin declares a `dependsOn`, which Nx then keeps. Before, such an addition was never blamed on an entry where the rebuild did not give the field: with an entry that added `^check` to every crate's `check` and another plugin that only tagged one crate, that crate drew the warning that the plugin cannot tell which configuration changed the target instead of the entry's. The review of nxr-gyyhdj found that one field that the rebuild did not give had made the plugin leave the whole target with a warning: where a crate's declared `dependsOn` named a crate that a `project.json` renamed, an entry narrowed by a `filter` to that crate replaced its `inputs`, its `outputs` or, by `dependsOn: []`, its dependency on the lockfile task, and graph creation went on with a warning. The review of that change found two more ways through, both ending in a cache hit of a result that the task would not give: an entry filtered to a plugin listed before this one, which had given a crate's `check` its executor first, replaced the inputs, which the synthesis with this plugin as the source did not lay over the target; and an entry filtered to a tag that another plugin gave a crate turned on caching for a `check` that the crate's Cargo metadata set uncached, which drew only the warning, while the executor's check did not know that reason. A lost `inputs`, `outputs` or `dependsOn` entry that no entry is blamed for is judged as **Other layers** says. Caching that is on and a `dependsOn` entry that is added, where no entry is blamed for them and the folder's files do not explain them, the plugin does not attribute: it warns that it cannot tell which configuration changed the target, names the project, the target and those fields, and points to `nx show target <project>:<target> --json` and its `sourceMap`. For caching, that warning rests on the executor's check of a task's merged configuration, which fails a task that caches a target which the plugin leaves uncached in its project, for every reason that leaves it uncached, a target table's `cache = false` included ([[DES-OUTPUTS]]), whichever layer turned caching on. Nx's normalisation of `dependsOn` for the task graph decides which projects an added entry reaches. These parts of Nx are not public API. They are loaded only when a target differs, and where the installed Nx lacks one, graph creation fails with the error of [[DES-DIAGNOSTICS]].
696
+
697
+ **Other layers.** Besides `targetDefaults`, Nx merges over the plugin's targets the nodes of the plugins that `nx.json` lists after this one, and the `project.json` and `package.json` in the project's folder. A later node's target that names no executor, or the plugin's own, replaces each list of the plugin's that it sets without `"..."`, and the task still runs the plugin's executor; one that names another executor or a command replaces the whole target, which the check then leaves alone ([[EVD-NX-24-PLUGIN-NODES]], "Other layers"). So the plugin compares what each of the inferred target's `inputs`, `outputs` and `dependsOn` means in the merged target with what it means in the rebuilds of **Which layer** with the `targetDefaults` layer, one for each plugin that may be the source of the target, each made of the plugin's projects, those elements and the folder's own `project.json` and `package.json`. This comparison approximates what Nx hashes; it does not ask Nx's native hash planner, which plans each task's key from the unexpanded lists, and its reading can differ from that plan in both directions ([[RISK-GUARD-HASH-PLAN]]). For `inputs`, both lists are first expanded as the JS helpers of Nx's task hasher expand them ([[EVD-NX-24-PLUGIN-NODES]], "What a list means"): a name that the project's named inputs hold stands for their definition, recursively, where the project's own definition replaces that of `nx.json`, which replaces Nx's built-in `default`; for a target without `inputs`, the guard reads `default` of the project itself and of its dependencies, as those helpers do, although the native planner was seen to plan the project's files for such a target where `default` was defined anew; an object entry counts as the project's own named input only where it has no `dependencies` and no `projects`; and an entry for the dependencies or for other projects, such as `^default`, stays as it is written, without a comparison of what those projects define. A list counts as weakened where it lacks an entry that the rebuild's has, or holds a negated pattern, one that starts with `!`, that the rebuild's lacks: in those helpers, a negated pattern applies to all of a project's own inputs, so one added pattern, or one in a named input that a layer defines anew, can take files out of the key, and an output pattern with `!` takes files out of what a cache hit restores. The guard counts every such added pattern, also where the native plan stays the same, as for a pattern under `{workspaceRoot}` or one for the dependencies, which is then refused without need. Entries compare as JSON with sorted keys, so an entry whose `params`, `options`, `projects` or pattern changed counts as lacking the original. The guard does not report what it reads as widening only: an added input whose expansion, as it reads it, holds no negated pattern, such as a positive file set, a variable, a command, external dependencies, dependency outputs or an input of other projects; an added output without `!`; and an added dependency, which only adds tasks (the warning below). Its reading misses some forms that narrow the native plan: a self input written as `{ "input": <name>, "dependencies": false }`, whose definition it does not expand, and a named input that another layer defines anew for a project that a `^` input reads ([[RISK-GUARD-HASH-PLAN]]). Where one rebuild gives a list that the merged one does not weaken, nothing is reported for it. Otherwise, and where no entry of `targetDefaults` is blamed for that field (**Which layer**), the weakened list is an error, also where `targetDefaults` is empty or none of its keys reaches the target. Each field is judged on its own here as well. The rebuilds hold what the folder's files do, so a list that they weaken themselves is not reported: it is the project's own statement, as [[REQ-METADATA-OVERRIDES]] gives those files precedence, and so is a named input that `nx.json` defines, since both sides read it. A weakening that they do not explain comes from another plugin, in practice one listed after this one, since the plugin's lists and named inputs replace those of a plugin listed before it. The message names each project and target, and for each field up to three of its lost entries with the number of the others, the entries that leave files out, and each named input that another layer defines anew with what its definition loses, and the plugins that `nx.json` lists after this one, and gives the fixes: an `exclude` of the project's folder on that plugin's entry; `"..."` in the lists that the plugin gives the target, and no negated pattern or named input of its own for the project, where the plugin is the repository's own; the change written into the `project.json` in the project's folder, which the rebuilds then hold; and, where a lost entry names a project, the name of that project as the merged graph has it. It points to `nx show target <project>:<target> --json`, whose `sourceMap` names the plugin behind each field. The maintainer decided this on 15 November 2026, word for word "Error unless the crate's own files explain it (Recommended)". Not chosen were an error for a loss from any layer, which would take from `project.json` and `package.json` the precedence that [[REQ-METADATA-OVERRIDES]] promises; a warning with the executor failing the task before cargo runs, which needs the most machinery (the inferred lists in each target's metadata, a comparison in the executor and another channel through `createMetadata`) for a rare setup; and leaving such changes outside the guard, which allows a stale hit without any sign. Before, such a loss drew only the warning that the plugin cannot tell which configuration changed the target where a key of `targetDefaults` could reach it, and nothing otherwise: with a plugin listed after this one that gave a crate's `check` the inputs `["default"]`, `nx run api:check` was restored from the cache after a compile error in a crate that `api` depends on ([[EVD-NX-24-PLUGIN-NODES]]). The review of that rule found two ways in which a later plugin weakened the key while every entry stayed, both ending in such a cache hit in both plugin modes: `"inputs": ["...", "!{projectRoot}/src/**/*"]` on a crate's `check`, after which a compile error in the crate's own source was restored as a success, and a project-level `namedInputs` that defined `default` anew as `["{projectRoot}/Cargo.toml"]`. The control plane decided the same day that the maintainer's rule applies to what a list means, as above. A plugin that replaces a target with the plugin's executor under another name, such as `rust-alias:cargo` from a second installation of the package, and supplies a `cargo` record in its metadata itself circumvents the guard deliberately, which lies outside what it can tell from the plugin's own targets.
698
+
699
+ A project reference that the plugin cannot give the name that Nx gave it (**Which layer**) stays a difference, and a lost one counts as a loss: Nx writes the final name of a project that a later file renames, such as one that its `package.json` names `web` and its `project.json` renames `web-app`, into a crate's declared reference to `web`, while the rebuild, which reads only the crate's own folder, keeps `web`. Graph creation then fails although nothing is lost. The message's last fix resolves it: a reference to the project's final name, which Nx leaves as it is. Only a target table of the crate's Cargo metadata declares a reference to another plugin's project, so a repository without such a reference never meets the case, and a `project.json` or `package.json` in the crate's own folder never causes it, since the rebuild reads them.
700
+
701
+ Caching needs no rule of its own: the executor fails every cached task of a target that the plugin leaves uncached in its project, whichever layer turned caching on ([[DES-OUTPUTS]], "Per project"), so caching that another plugin turns on stores no result, and the warning of **Which layer** for `cache` rests on that check, which is the complete answer for caching. An added `dependsOn` entry that no element of `targetDefaults` lists keeps that warning as well, because an addition only queues tasks and leaves results correct ([[EVD-NXRUST-BUILD-DEPS]]), so nothing at run time needs to back it. An entry that another layer adds to `inputs` or `outputs` is not reported where the guard reads it as widening only, as above; a negated pattern, or a named input that holds one, counts as a weakening. Every other difference that drew the warning before, a lost `inputs`, `outputs` or `dependsOn` entry, is now either an error or a weakening that the folder's files explain.
702
+
703
+ **Message.** One paragraph per entry and severity names the key and its elements, says what the entry does to which targets of which projects, with their manifests, and lists the ways to narrow the entry that fit: a `filter` on `projects` or `executor`; an empty entry keyed by the targets' executor, which Nx chooses before an entry keyed by the target's name; removing the field from an entry keyed by the plugin's executor; and `"..."` in a list that replaces. Errors stop graph creation, and warnings are printed where [[DES-DIAGNOSTICS]] says. `createDependencies` hands each warning, with the targets it concerns, to `createMetadata`, which puts it into the metadata of those targets' projects for the executor, whose tasks of those targets print it at their start. So that a cache hit shows the current state, the digest of a project's warnings also covers the `dependsOn` entries that `targetDefaults` adds to the project's inferred targets as far as `createNodes` sees them: its own projects, Nx's synthesis of target defaults, run once for each plugin that may be the source of the targets as in **Which layer**, which `createNodes` cannot see either, and the `package.json` and `project.json` on disk in the projects' folders, leaving out entries whose form shows that they reach only the project's own tasks. Before, only the run with this plugin as the source counted, so that an entry from a file that `nx.json` extends, filtered to a plugin listed before this one that gave a crate's target its executor, changed no key, and a cache hit replayed the task's output without the warning. An entry whose `filter` selects projects by a tag, which another plugin may give, counts for every project with a target that its key can reach, since `createNodes` cannot decide it; filters by name, folder, plugin or executor keep their exact reading. That matters for entries from a file that `nx.json` extends: Nx hashes `nx.json` itself into every key, but not the file it extends ([[EVD-NX-24-WARNING-CHANNELS]]). Where only the list of projects that a warning names changes, a cache hit of another crate shows the earlier list until its key changes; an entry that counts without applying, or that adds only own tasks in a form that does not show it, causes one run without a warning; and a `dependsOn` that another plugin changes reaches no key ([[DES-DIAGNOSTICS]], "Warnings that `createDependencies` finds"). Graph creation never edits `targetDefaults`, and `init` only adds the empty entries that are missing.
704
+ :::