@smoothbricks/nx-plugin 0.4.28 → 0.4.30

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 (158) hide show
  1. package/README.md +277 -89
  2. package/dist/bin/smoo-nx-test-clocks.d.ts +3 -0
  3. package/dist/bin/smoo-nx-test-clocks.d.ts.map +1 -0
  4. package/dist/bin/smoo-nx-test-clocks.js +28 -0
  5. package/dist/bounded-test-policy.d.ts +8 -8
  6. package/dist/bounded-test-policy.d.ts.map +1 -1
  7. package/dist/bounded-test-policy.js +18 -30
  8. package/dist/cargo-closure-input.d.ts +23 -0
  9. package/dist/cargo-closure-input.d.ts.map +1 -1
  10. package/dist/cargo-closure-input.js +41 -9
  11. package/dist/cargo-source-hash.d.ts.map +1 -1
  12. package/dist/cargo-source-hash.js +42 -19
  13. package/dist/ensure-built-receipt.d.ts +40 -6
  14. package/dist/ensure-built-receipt.d.ts.map +1 -1
  15. package/dist/ensure-built-receipt.js +297 -159
  16. package/dist/ensure-built-witness.d.ts +65 -4
  17. package/dist/ensure-built-witness.d.ts.map +1 -1
  18. package/dist/ensure-built-witness.js +2237 -23
  19. package/dist/ensure-built.d.ts +99 -1
  20. package/dist/ensure-built.d.ts.map +1 -1
  21. package/dist/ensure-built.js +45 -56
  22. package/dist/executors/bounded-exec/cpu-pool.d.ts +22 -7
  23. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -1
  24. package/dist/executors/bounded-exec/cpu-pool.js +51 -22
  25. package/dist/executors/bounded-exec/executor.d.ts +12 -3
  26. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  27. package/dist/executors/bounded-exec/executor.js +174 -51
  28. package/dist/executors/bounded-exec/no-space.d.ts +8 -0
  29. package/dist/executors/bounded-exec/no-space.d.ts.map +1 -0
  30. package/dist/executors/bounded-exec/no-space.js +31 -0
  31. package/dist/executors/bounded-exec/ram-temp.d.ts +20 -11
  32. package/dist/executors/bounded-exec/ram-temp.d.ts.map +1 -1
  33. package/dist/executors/bounded-exec/ram-temp.js +42 -17
  34. package/dist/executors/bounded-exec/verdict.d.ts +34 -4
  35. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  36. package/dist/executors/bounded-exec/verdict.js +54 -3
  37. package/dist/generators/bun-test-tracing/generator.js +2 -2
  38. package/dist/graph-input-contract.d.ts +102 -0
  39. package/dist/graph-input-contract.d.ts.map +1 -0
  40. package/dist/graph-input-contract.js +637 -0
  41. package/dist/index.d.ts +12 -5
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +17 -3
  44. package/dist/managed-files/ci-workflow.d.ts.map +1 -1
  45. package/dist/managed-files/ci-workflow.js +5 -2
  46. package/dist/managed-files/publish-workflow.d.ts +11 -1
  47. package/dist/managed-files/publish-workflow.d.ts.map +1 -1
  48. package/dist/owned-installation.d.ts +14 -0
  49. package/dist/owned-installation.d.ts.map +1 -0
  50. package/dist/owned-installation.js +324 -0
  51. package/dist/producer-receipts.d.ts +19 -0
  52. package/dist/producer-receipts.d.ts.map +1 -0
  53. package/dist/producer-receipts.js +926 -0
  54. package/dist/test-backstop.d.ts +9 -0
  55. package/dist/test-backstop.d.ts.map +1 -0
  56. package/dist/test-backstop.js +10 -0
  57. package/dist/test-clock-policy.d.ts +30 -0
  58. package/dist/test-clock-policy.d.ts.map +1 -0
  59. package/dist/test-clock-policy.js +686 -0
  60. package/dist/testing.d.ts +8 -0
  61. package/dist/testing.d.ts.map +1 -1
  62. package/dist/testing.js +66 -1
  63. package/managed/raw/patches/nx@23.2.1.patch +328 -50
  64. package/managed/raw/tooling/direnv/developer-links.ts +148 -29
  65. package/managed/raw/tooling/direnv/devenv.smoo.nix +7 -7
  66. package/managed/raw/tooling/direnv/github-actions-bootstrap.sh +14 -5
  67. package/managed/raw/tooling/direnv/linked-snapshots.ts +206 -40
  68. package/managed/raw/tooling/direnv/repo-path +15 -2
  69. package/managed/raw/tooling/direnv/setup-environment.ts +179 -115
  70. package/managed/templates/github/actions/cache-node-modules/action.yml +9 -0
  71. package/managed/templates/github/actions/setup-devenv/action.yml +63 -7
  72. package/nextest.toml +1 -1
  73. package/package.json +25 -9
  74. package/src/__tests__/cargo-closure-fixture.ts +113 -0
  75. package/src/__tests__/counted-cargo.ts +8 -25
  76. package/src/__tests__/directory-change.ts +27 -0
  77. package/src/__tests__/fixture-nx-env.ts +7 -0
  78. package/src/__tests__/owned-installation.ts +14 -0
  79. package/src/__tests__/past-tick.ts +12 -0
  80. package/src/bin/smoo-nx-bound-failures.test.ts +1 -1
  81. package/src/bin/smoo-nx-test-clocks.ts +29 -0
  82. package/src/bounded-test-policy.test.ts +36 -22
  83. package/src/bounded-test-policy.ts +18 -32
  84. package/src/bun-bootstrap.test.ts +1 -1
  85. package/src/cargo-closure-input.property.test.ts +50 -0
  86. package/src/cargo-closure-input.test.ts +73 -121
  87. package/src/cargo-closure-input.ts +47 -8
  88. package/src/cargo-closure-key.test.ts +239 -0
  89. package/src/cargo-resolve-cache.test.ts +168 -31
  90. package/src/cargo-source-hash.test.ts +78 -3
  91. package/src/cargo-source-hash.ts +48 -30
  92. package/src/cross-check-policy.test.ts +2 -2
  93. package/src/ensure-built-receipt.test.ts +111 -16
  94. package/src/ensure-built-receipt.ts +294 -149
  95. package/src/ensure-built-witness.test.ts +306 -13
  96. package/src/ensure-built-witness.ts +255 -24
  97. package/src/ensure-built.test.ts +228 -102
  98. package/src/ensure-built.ts +127 -66
  99. package/src/executors/bounded-exec/cpu-pool.test.ts +134 -32
  100. package/src/executors/bounded-exec/cpu-pool.ts +64 -20
  101. package/src/executors/bounded-exec/cpu-tokens.test.ts +2 -2
  102. package/src/executors/bounded-exec/disk-lease.test.ts +47 -13
  103. package/src/executors/bounded-exec/executor-host.test.ts +74 -52
  104. package/src/executors/bounded-exec/executor.test.ts +343 -97
  105. package/src/executors/bounded-exec/executor.ts +192 -56
  106. package/src/executors/bounded-exec/hang-diagnostics.test.ts +14 -8
  107. package/src/executors/bounded-exec/no-space.ts +40 -0
  108. package/src/executors/bounded-exec/progress.test.ts +1 -1
  109. package/src/executors/bounded-exec/ram-temp-host.test.ts +51 -21
  110. package/src/executors/bounded-exec/ram-temp.test.ts +92 -16
  111. package/src/executors/bounded-exec/ram-temp.ts +49 -20
  112. package/src/executors/bounded-exec/verdict.test.ts +127 -22
  113. package/src/executors/bounded-exec/verdict.ts +78 -3
  114. package/src/generators/bounded-test-targets/generator.test.ts +1 -3
  115. package/src/generators/bun-test-tracing/generator.test.ts +2 -2
  116. package/src/generators/bun-test-tracing/generator.ts +2 -2
  117. package/src/graph-input-contract.test.ts +379 -0
  118. package/src/graph-input-contract.ts +627 -0
  119. package/src/index.test.ts +3 -3
  120. package/src/index.ts +24 -3
  121. package/src/linked-snapshots.nx.test.ts +112 -30
  122. package/src/managed-files/ci-workflow.ts +5 -2
  123. package/src/managed-files/publish-workflow.ts +12 -1
  124. package/src/managed-files/repo-path.test.ts +44 -1
  125. package/src/managed-files/setup-devenv-free-disk.test.ts +95 -0
  126. package/src/nextest-code-bound.test.ts +23 -17
  127. package/src/nextest-extraction.test.ts +114 -4
  128. package/src/nextest-partitions.test.ts +7 -1
  129. package/src/nx-cache-restore-mtime.test.ts +2 -2
  130. package/src/nx-daemon-claim.test.ts +10 -8
  131. package/src/nx-daemon-idle-cpu.test.ts +0 -1
  132. package/src/nx-daemon-idle-policy.test.ts +61 -1
  133. package/src/nx-daemon-ignore-files.test.ts +2 -2
  134. package/src/nx-daemon-validity.test.ts +36 -22
  135. package/src/nx-dot-input-policy.test.ts +5 -5
  136. package/src/nx-files-archive-racy.test.ts +1 -1
  137. package/src/nx-incomplete-run-summary.test.ts +1 -1
  138. package/src/nx-plugin-load-errors.test.ts +2 -2
  139. package/src/nx-project-graph-errors.test.ts +70 -0
  140. package/src/nx-skipped-task-exit.test.ts +2 -2
  141. package/src/nx-store-resolution.test.ts +7 -25
  142. package/src/nx-task-output-lease.test.ts +3 -3
  143. package/src/nx-use-local.test.ts +7 -5
  144. package/src/owned-installation.ts +174 -0
  145. package/src/producer-receipts.test.ts +164 -0
  146. package/src/producer-receipts.ts +636 -0
  147. package/src/runtime-input.test.ts +1 -1
  148. package/src/serial-group-wiring.test.ts +4 -4
  149. package/src/task-results.test.ts +18 -16
  150. package/src/test-backstop.ts +11 -0
  151. package/src/test-clock-policy.test.ts +338 -0
  152. package/src/test-clock-policy.ts +708 -0
  153. package/src/test-timings.test.ts +2 -2
  154. package/src/testing.test.ts +5 -5
  155. package/src/testing.ts +67 -1
  156. package/src/typecheck-test-policy.test.ts +1 -1
  157. package/src/typescript-resolution.test.ts +76 -0
  158. package/test-timings.json +8 -0
@@ -15,8 +15,9 @@
15
15
  *
16
16
  * - every provider workspace package in the declared package's link closure:
17
17
  * its manifest, the files its manifest's `files` publishes, and its
18
- * `tsconfig.json` with every relative `extends` (Bun applies a source
19
- * module's tsconfig `paths`);
18
+ * `tsconfig.json` with every relative `extends` and project `references`
19
+ * entry it reaches (Bun applies a source module's tsconfig `paths`, and a
20
+ * solution-style config gives sources their options through a reference);
20
21
  * - the provider root manifest, which owns the files outside every package;
21
22
  * - the native library each declared artifact module's `nativeArtifactPath({})`
22
23
  * names: the checkout's own build, never a consumer override;
@@ -26,7 +27,7 @@
26
27
  *
27
28
  * Provenance is the provider's own Nx producer receipt. Every declared target
28
29
  * must be a probe hit (the read-only `probeBuilt`, which runs and
29
- * writes nothing), all at one HEAD, and every copied provider file must be
30
+ * writes nothing), all at one committed tree, and every copied provider file must be
30
31
  * either the blob HEAD tracks at its path or an output the receipt inventories
31
32
  * with the same bytes. A stale output, a modified or untracked source file, or
32
33
  * a target that is not current refuses with its cause; nothing in the provider
@@ -37,11 +38,18 @@
37
38
  * A snapshot is named by the SHA-256 of its census (every entry's path, type,
38
39
  * executable bit, and its bytes or link text) together with its producer
39
40
  * receipt identity: the provider root, HEAD and its tree, the probe's file-input
40
- * provenance, and every task id and hash. Other bytes, another commit or another
41
- * task hash is another snapshot, and nothing binds without a fresh probe, so no
42
- * name or provenance is ever reused for a provider state it does not describe.
43
- * Files are sealed read-only, and a reader that trusts a snapshot verifies its
44
- * census and name (`verifySnapshot`): modes and paths prove nothing.
41
+ * provenance, every task id and hash, and the digest of each target's whole
42
+ * producer completion record (argv, environment identity, inputs, tools, output
43
+ * digest, wall time). Other bytes, another commit, another task hash or another
44
+ * production is another snapshot, and nothing is captured without a fresh probe,
45
+ * so no name or provenance is ever reused for a provider state it does not
46
+ * describe. When no fresh snapshot can be made, an alias keeps the sealed one
47
+ * its receipt records (`recordedSnapshot`), verified: the provider state it was
48
+ * taken from, not the provider's current one.
49
+ * A receipt without a producer record of a known version, as an older plugin's
50
+ * cache hit gives, is refused. Files are sealed read-only, and a reader that
51
+ * trusts a snapshot verifies its census, its retained producer records and its
52
+ * name (`verifySnapshot`): modes and paths prove nothing.
45
53
  *
46
54
  * The store is `.cache/linked-snapshots` in the consumer checkout. Under cowshed
47
55
  * it is declared build state (`.cowshed.toml` `[build] state`), so it lives on
@@ -50,9 +58,9 @@
50
58
  * has not linked yet is refused, never filled: a refresh discards a real
51
59
  * directory at a declared path.
52
60
  *
53
- * Dependency-free except for the probe, which a capture loads from the
54
- * consumer's installed @smoothbricks/nx-plugin only when it needs one: shell
55
- * entry imports this before anything is installed.
61
+ * Dependency-free except for the probe, which a capture loads only when it
62
+ * needs one, from the @smoothbricks/nx-plugin its caller names (`pluginProbe`):
63
+ * shell entry imports this before anything is installed.
56
64
  */
57
65
 
58
66
  import { spawnSync } from 'node:child_process';
@@ -102,7 +110,7 @@ export type CensusEntry =
102
110
  | { readonly path: string; readonly type: 'file'; readonly executable: boolean; readonly sha256: string }
103
111
  | { readonly path: string; readonly type: 'symlink'; readonly linkText: string };
104
112
 
105
- /** The provider state a snapshot was copied from: its HEAD and the Nx tasks whose outputs it holds. */
113
+ /** The committed provider tree and original producer bases whose attested outputs the snapshot holds. */
106
114
  export interface SnapshotProvenance {
107
115
  readonly root: string;
108
116
  readonly head: string;
@@ -110,6 +118,8 @@ export interface SnapshotProvenance {
110
118
  /** How each probe vouched for its file inputs: exactly, or conservatively over the whole provider source. */
111
119
  readonly fileInputs: readonly string[];
112
120
  readonly tasks: readonly { readonly id: string; readonly hash: string }[];
121
+ /** Each declared target's producer completion record, by the SHA-256 of its canonical JSON. */
122
+ readonly producers: readonly { readonly target: string; readonly basis: string; readonly sha256: string }[];
113
123
  }
114
124
 
115
125
  export interface SnapshotReceipt {
@@ -119,12 +129,19 @@ export interface SnapshotReceipt {
119
129
  /** The declared package's directory inside the snapshot. */
120
130
  readonly packagePath: string;
121
131
  readonly provenance: SnapshotProvenance;
132
+ /** The producer completion records `provenance.producers` digests, retained verbatim in target order. */
133
+ readonly producerReceipts: readonly unknown[];
122
134
  readonly census: readonly CensusEntry[];
123
135
  }
124
136
 
125
- export type SnapshotBinding =
126
- | { readonly kind: 'snapshot'; readonly id: string; readonly directory: string }
127
- | { readonly kind: 'refused'; readonly reason: string };
137
+ /** A sealed snapshot an alias binds: its id and the declared package's directory inside it. */
138
+ export interface SealedSnapshot {
139
+ readonly kind: 'snapshot';
140
+ readonly id: string;
141
+ readonly directory: string;
142
+ }
143
+
144
+ export type SnapshotBinding = SealedSnapshot | { readonly kind: 'refused'; readonly reason: string };
128
145
 
129
146
  /** Asks the provider whether `target` is current, without running anything. */
130
147
  export type ProducerProbe = (target: string, providerRoot: string) => Promise<EnsureBuiltProbeResult>;
@@ -148,6 +165,11 @@ type ProducerOutput = Extract<
148
165
  { readonly disposition: 'hit' }
149
166
  >['receipt']['tasks'][number]['outputs'][number];
150
167
 
168
+ type ProducerRecord = Extract<EnsureBuiltProbeResult, { readonly disposition: 'hit' }>['receipt']['producer'];
169
+
170
+ /** The producer protocol versions this consumer reads. */
171
+ const PRODUCER_VERSION = 1;
172
+
151
173
  /**
152
174
  * The snapshot `source` binds to now: its provider is probed, copied and attested every time, and the result is
153
175
  * the sealed snapshot of exactly that census and receipt, published now or verified when it already exists. A
@@ -158,7 +180,7 @@ export async function snapshotBinding(
158
180
  name: string,
159
181
  source: string,
160
182
  declaration: SnapshotDeclaration,
161
- probe: ProducerProbe = installedProbe(root),
183
+ probe: ProducerProbe,
162
184
  ): Promise<SnapshotBinding> {
163
185
  try {
164
186
  const store = snapshotStore(root);
@@ -193,19 +215,21 @@ function snapshotStore(root: string): string {
193
215
  }
194
216
 
195
217
  /**
196
- * The consumer's installed nx-plugin probe, loaded when a capture first asks. An installed plugin without the
197
- * read-only `probeBuilt` is refused before anything is called: its `ensureBuilt` builds, and a capture must never
198
- * write the provider.
218
+ * The probe of the @smoothbricks/nx-plugin that `from` resolves, loaded when a capture first asks. A plugin without
219
+ * the read-only `probeBuilt` is refused before anything is called: its `ensureBuilt` builds, and a capture must never
220
+ * write the provider. `from` is the plugin the consumer binds, never merely what its last install left: a plain
221
+ * `bun install` re-points a declared plugin alias at the lockfile's published version before the postinstall that
222
+ * captures runs (developer-links.ts).
199
223
  */
200
- function installedProbe(root: string): ProducerProbe {
224
+ export function pluginProbe(from: string): ProducerProbe {
201
225
  return async (target, providerRoot) => {
202
226
  // Dynamic by necessity: this file runs before anything is installed, and only a capture needs the plugin.
203
- const specifier = Bun.resolveSync('@smoothbricks/nx-plugin/ensure-built', root);
227
+ const specifier = Bun.resolveSync('@smoothbricks/nx-plugin/ensure-built', from);
204
228
  const plugin: unknown = await import(specifier);
205
229
  const probeBuilt = typeof plugin === 'object' && plugin !== null ? Reflect.get(plugin, 'probeBuilt') : undefined;
206
230
  if (!isProbeBuilt(probeBuilt)) {
207
231
  throw new SnapshotRefusal(
208
- `the installed @smoothbricks/nx-plugin (${specifier}) has no read-only probeBuilt, so ${target} cannot be vouched for without building it; install a plugin that exports probeBuilt`,
232
+ `the @smoothbricks/nx-plugin resolved from ${from} (${specifier}) has no read-only probeBuilt, so ${target} cannot be vouched for without building it; bind a plugin that exports probeBuilt`,
209
233
  );
210
234
  }
211
235
  return probeBuilt({ target, cwd: providerRoot });
@@ -356,10 +380,21 @@ function readManifest(manifestPath: string): Record<string, unknown> {
356
380
  return Object.fromEntries(Object.entries(manifest));
357
381
  }
358
382
 
359
- /** A package's `tsconfig.json` and every configuration it extends, by relative path only. */
383
+ /**
384
+ * A package's `tsconfig.json` and every configuration it reaches, by relative path only: each `extends` and each
385
+ * project `references` entry. A solution-style `tsconfig.json` (no files of its own) gives its sources their compiler
386
+ * options only through a referenced project, so a source consumer that reads the package's tsconfig needs that
387
+ * project too; it is a compile input, not documentation.
388
+ */
360
389
  function tsconfigChain(config: string): string[] {
361
390
  if (lstatSync(config, { throwIfNoEntry: false }) === undefined) return [];
362
391
  const chain: string[] = [];
392
+ const relative = (file: string, edge: 'extends' | 'references', target: unknown): string => {
393
+ if (typeof target !== 'string' || !(target.startsWith('./') || target.startsWith('../'))) {
394
+ throw new SnapshotRefusal(`${file} ${edge} ${JSON.stringify(target)}, which a snapshot cannot carry`);
395
+ }
396
+ return path.resolve(path.dirname(file), target);
397
+ };
363
398
  const visit = (file: string) => {
364
399
  if (chain.includes(file)) return;
365
400
  chain.push(file);
@@ -369,16 +404,31 @@ function tsconfigChain(config: string): string[] {
369
404
  } catch (error) {
370
405
  throw new SnapshotRefusal(`cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
371
406
  }
372
- const extended = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'extends') : undefined;
373
- if (extended === undefined) return;
374
- for (const base of Array.isArray(extended) ? extended : [extended]) {
375
- if (typeof base !== 'string' || !(base.startsWith('./') || base.startsWith('../'))) {
376
- throw new SnapshotRefusal(`${file} extends ${JSON.stringify(base)}, which a snapshot cannot carry`);
407
+ if (typeof parsed !== 'object' || parsed === null) return;
408
+ const extended: unknown = Reflect.get(parsed, 'extends');
409
+ if (extended !== undefined) {
410
+ for (const base of Array.isArray(extended) ? extended : [extended]) {
411
+ const resolved = relative(file, 'extends', base);
412
+ const named = path.extname(resolved) === '.json' ? resolved : `${resolved}.json`;
413
+ if (lstatSync(named, { throwIfNoEntry: false }) === undefined) {
414
+ throw new SnapshotRefusal(`${file} extends ${base}, which does not exist`);
415
+ }
416
+ visit(named);
377
417
  }
378
- const resolved = path.resolve(path.dirname(file), base);
379
- const named = path.extname(resolved) === '.json' ? resolved : `${resolved}.json`;
418
+ }
419
+ const references: unknown = Reflect.get(parsed, 'references');
420
+ if (references === undefined) return;
421
+ if (!Array.isArray(references)) throw new SnapshotRefusal(`${file} references is not an array`);
422
+ for (const reference of references) {
423
+ const target: unknown =
424
+ typeof reference === 'object' && reference !== null ? Reflect.get(reference, 'path') : undefined;
425
+ const resolved = relative(file, 'references', target);
426
+ // A reference names a project directory (its tsconfig.json) or a configuration file.
427
+ const named = lstatSync(resolved, { throwIfNoEntry: false })?.isDirectory()
428
+ ? path.join(resolved, 'tsconfig.json')
429
+ : resolved;
380
430
  if (lstatSync(named, { throwIfNoEntry: false }) === undefined) {
381
- throw new SnapshotRefusal(`${file} extends ${base}, which does not exist`);
431
+ throw new SnapshotRefusal(`${file} references ${String(target)}, which does not exist`);
382
432
  }
383
433
  visit(named);
384
434
  }
@@ -488,8 +538,8 @@ async function capture(
488
538
  probe: ProducerProbe,
489
539
  fingerprint: string,
490
540
  ): Promise<string> {
491
- const { provenance, outputs } = await producerReceipt(plan, declaration, probe);
492
- const tracked = trackedBlobs(plan, provenance.head);
541
+ const { provenance, producers, outputs } = await producerReceipt(plan, declaration, probe);
542
+ const tracked = trackedBlobs(plan, provenance.headTree);
493
543
  const incoming = mkdtempSync(path.join(store, '.incoming-'));
494
544
  try {
495
545
  const census: CensusEntry[] = [];
@@ -522,6 +572,7 @@ async function capture(
522
572
  name: plan.name,
523
573
  packagePath: plan.packagePath,
524
574
  provenance,
575
+ producerReceipts: producers,
525
576
  census,
526
577
  };
527
578
  writeFileSync(path.join(incoming, SNAPSHOT_RECEIPT), `${JSON.stringify(receipt)}\n`, { mode: 0o444 });
@@ -533,20 +584,26 @@ async function capture(
533
584
  }
534
585
 
535
586
  /**
536
- * Every declared target probed as a hit at one HEAD, and the outputs those hits inventory by path. A target that
587
+ * Every declared target has a producer hit for one committed tree; each original basis remains provenance. A target that
537
588
  * is not current is refused with the `nx run` that makes it so.
538
589
  */
539
590
  async function producerReceipt(
540
591
  plan: SnapshotPlan,
541
592
  declaration: SnapshotDeclaration,
542
593
  probe: ProducerProbe,
543
- ): Promise<{ readonly provenance: SnapshotProvenance; readonly outputs: ReadonlyMap<string, ProducerOutput> }> {
594
+ ): Promise<{
595
+ readonly provenance: SnapshotProvenance;
596
+ readonly producers: readonly ProducerRecord[];
597
+ readonly outputs: ReadonlyMap<string, ProducerOutput>;
598
+ }> {
544
599
  if (declaration.targets.length === 0)
545
600
  throw new SnapshotRefusal(`${plan.name} declares no provider targets to vouch for its build`);
546
601
  let head: { readonly head: string; readonly headTree: string } | undefined;
547
602
  const tasks = new Map<string, string>();
548
603
  const fileInputs = new Set<string>();
549
604
  const outputs = new Map<string, ProducerOutput>();
605
+ const producers: ProducerRecord[] = [];
606
+ const identities: SnapshotProvenance['producers'][number][] = [];
550
607
  for (const target of declaration.targets) {
551
608
  const result = await probe(target, plan.root);
552
609
  switch (result.disposition) {
@@ -568,10 +625,15 @@ async function producerReceipt(
568
625
  throw new SnapshotRefusal(`${target} was probed in ${receipt.workspaceRoot}, not ${plan.root}`);
569
626
  }
570
627
  head ??= { head: receipt.head, headTree: receipt.headTree };
571
- if (receipt.head !== head.head || receipt.headTree !== head.headTree) {
572
- throw new SnapshotRefusal(`${plan.root} moved from ${head.head} to ${receipt.head} while it was probed`);
628
+ if (receipt.headTree !== head.headTree) {
629
+ throw new SnapshotRefusal(
630
+ `${plan.root} moved from tree ${head.headTree} to ${receipt.headTree} while it was probed`,
631
+ );
573
632
  }
574
633
  fileInputs.add(receipt.fileInputProvenance);
634
+ const producer = producerOf(receipt, target, plan.root);
635
+ producers.push(producer);
636
+ identities.push({ target: producer.target, basis: receipt.head, sha256: sha256(canonicalJson(producer)) });
575
637
  for (const task of receipt.tasks) {
576
638
  const known = tasks.get(task.id);
577
639
  if (known !== undefined && known !== task.hash) {
@@ -595,12 +657,68 @@ async function producerReceipt(
595
657
  headTree: head.headTree,
596
658
  fileInputs: [...fileInputs].sort(compare),
597
659
  tasks: [...tasks].sort(([left], [right]) => compare(left, right)).map(([id, hash]) => ({ id, hash })),
660
+ producers: identities,
598
661
  },
662
+ producers,
599
663
  outputs,
600
664
  };
601
665
  }
602
666
 
603
- /** The blob HEAD tracks at each planned provider path, with its mode. */
667
+ /**
668
+ * The producer completion record a hit carries for `target`: present, of a version this consumer reads, produced for
669
+ * that target from a clean tracked tree, with inputs for every task the receipt inventories. A receipt without one is
670
+ * an older plugin's cache hit, which vouches for no production, and is refused rather than read some other way.
671
+ */
672
+ function producerOf(
673
+ receipt: Extract<EnsureBuiltProbeResult, { readonly disposition: 'hit' }>['receipt'],
674
+ target: string,
675
+ root: string,
676
+ ): ProducerRecord {
677
+ const present: unknown = Reflect.get(receipt, 'producer');
678
+ if (typeof present !== 'object' || present === null) {
679
+ throw new SnapshotRefusal(
680
+ `${target} in ${root} has no producer completion receipt: its plugin vouches only for a cache hit, so publish ${target} through a plugin with producer receipts and run it there`,
681
+ );
682
+ }
683
+ const version: unknown = Reflect.get(present, 'version');
684
+ if (version !== PRODUCER_VERSION) {
685
+ throw new SnapshotRefusal(
686
+ `${target} in ${root} has a producer receipt of unknown version ${JSON.stringify(version)}`,
687
+ );
688
+ }
689
+ const producer = receipt.producer;
690
+ if (producer.target !== target) {
691
+ throw new SnapshotRefusal(`${target} in ${root} carries the producer receipt of ${producer.target}`);
692
+ }
693
+ if (producer.trackedTreeClean !== true) {
694
+ throw new SnapshotRefusal(`${target} in ${root} was produced from a tracked tree that was not clean`);
695
+ }
696
+ const described = new Set(producer.inputs.map(({ taskId }) => taskId));
697
+ for (const task of receipt.tasks) {
698
+ if (!described.has(task.id)) {
699
+ throw new SnapshotRefusal(`${target} in ${root} has a producer receipt that records no inputs of ${task.id}`);
700
+ }
701
+ }
702
+ return producer;
703
+ }
704
+
705
+ /** JSON with every object's keys in code-unit order, so one record has one digest wherever it was serialized. */
706
+ function canonicalJson(value: unknown): string {
707
+ if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
708
+ if (typeof value === 'object' && value !== null) {
709
+ const entries = Object.entries(value)
710
+ .filter(([, item]) => item !== undefined)
711
+ .sort(([left], [right]) => compare(left, right));
712
+ return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
713
+ }
714
+ return JSON.stringify(value);
715
+ }
716
+
717
+ /**
718
+ * The blob HEAD tracks at each planned provider path, with its mode. Git runs under the provider's own configuration
719
+ * alone: a sandboxed shell entry keeps the operator's HOME but may not read the operator's global configuration, and
720
+ * git dies on it (specs/cowshed/04_sandbox.md, the runtime-input contract).
721
+ */
604
722
  function trackedBlobs(
605
723
  plan: SnapshotPlan,
606
724
  head: string,
@@ -610,6 +728,7 @@ function trackedBlobs(
610
728
  .map(([relative]) => relative);
611
729
  const run = spawnSync('git', ['-C', plan.root, 'ls-tree', '-z', head, '--', ...paths], {
612
730
  encoding: 'utf8',
731
+ env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' },
613
732
  maxBuffer: 1 << 28,
614
733
  });
615
734
  if (run.error !== undefined || run.status !== 0) {
@@ -641,7 +760,7 @@ function attest(
641
760
  if (blob !== undefined) {
642
761
  if (gitBlobId(bytes, blob.id.length) !== blob.id || (blob.mode === '100755') !== executable) {
643
762
  throw new SnapshotRefusal(
644
- `${path.join(plan.root, relative)} differs from HEAD ${provenance.head}: a snapshot is one commit's source, so commit or discard it`,
763
+ `${path.join(plan.root, relative)} differs from tree ${provenance.headTree} (producer basis ${provenance.head}): a snapshot is committed source, so commit or discard it`,
645
764
  );
646
765
  }
647
766
  return;
@@ -649,7 +768,7 @@ function attest(
649
768
  const output = outputs.get(relative);
650
769
  if (output === undefined) {
651
770
  throw new SnapshotRefusal(
652
- `${path.join(plan.root, relative)} is neither tracked at HEAD ${provenance.head} nor an output Nx recorded for ${provenance.tasks.map(({ id }) => id).join(', ')}`,
771
+ `${path.join(plan.root, relative)} is neither tracked at tree ${provenance.headTree} (producer basis ${provenance.head}) nor an output Nx recorded for ${provenance.tasks.map(({ id }) => id).join(', ')}`,
653
772
  );
654
773
  }
655
774
  if (output.type !== 'file' || output.sha256 !== digest) {
@@ -691,6 +810,7 @@ function snapshotId(census: readonly CensusEntry[], provenance: SnapshotProvenan
691
810
  provenance.headTree,
692
811
  [...provenance.fileInputs].sort(compare),
693
812
  [...provenance.tasks].sort((left, right) => compare(left.id, right.id)).map(({ id, hash }) => [id, hash]),
813
+ provenance.producers.map(({ target, basis, sha256: digest }) => [target, basis, digest]),
694
814
  ]),
695
815
  );
696
816
  }
@@ -738,6 +858,25 @@ export function sealedSnapshotOf(
738
858
  }
739
859
  }
740
860
 
861
+ /**
862
+ * The sealed snapshot of `name` in this checkout's store that `linkText`, an alias's recorded link at `entry`, binds,
863
+ * once it verifies; or null when that text names no snapshot left in the store. When no new snapshot can be made the
864
+ * alias keeps this one: an install has re-pointed it at the lockfile's version before its postinstall runs, and a
865
+ * sealed snapshot never changes, so binding it again restores the binding the alias had, for the provider state it
866
+ * was taken from.
867
+ */
868
+ export function recordedSnapshot(root: string, entry: string, name: string, linkText: string): SealedSnapshot | null {
869
+ const target = path.resolve(root, path.dirname(entry), linkText);
870
+ const inside = path.relative(path.resolve(root, SNAPSHOT_STORE), target);
871
+ if (inside === '' || !contained(inside)) return null;
872
+ const directory = path.resolve(root, SNAPSHOT_STORE, inside.split(path.sep)[0] ?? inside);
873
+ if (readSealed(directory) === null) return null;
874
+ const receipt = verifySnapshot(directory);
875
+ if (receipt.name !== name || path.join(directory, receipt.packagePath) !== target)
876
+ throw new SnapshotRefusal(`${entry} records ${linkText}, which is not snapshot ${receipt.id}'s ${name}`);
877
+ return { kind: 'snapshot', id: receipt.id, directory: target };
878
+ }
879
+
741
880
  /**
742
881
  * The snapshot's receipt once every entry under `directory` matches its census exactly: the same paths, types,
743
882
  * executable bits and bytes or link text, and nothing else. Anything else refuses, naming the entry.
@@ -747,6 +886,20 @@ export function verifySnapshot(directory: string): SnapshotReceipt {
747
886
  if (receipt === null) throw new SnapshotRefusal(`${directory} is not a sealed snapshot`);
748
887
  if (snapshotId(receipt.census, receipt.provenance) !== receipt.id)
749
888
  throw new SnapshotRefusal(`${directory} has a census and receipt that are not its name`);
889
+ if (
890
+ receipt.producerReceipts.length !== receipt.provenance.producers.length ||
891
+ receipt.producerReceipts.some((record, index) => {
892
+ const named = receipt.provenance.producers[index];
893
+ return (
894
+ named === undefined ||
895
+ sha256(canonicalJson(record)) !== named.sha256 ||
896
+ typeof record !== 'object' ||
897
+ record === null ||
898
+ Reflect.get(record, 'target') !== named.target
899
+ );
900
+ })
901
+ )
902
+ throw new SnapshotRefusal(`${directory} retains producer receipts that are not the ones its name binds`);
750
903
  const expected = new Map(receipt.census.map((entry) => [entry.path, entry]));
751
904
  let seen = 0;
752
905
  const walk = (at: string) => {
@@ -793,8 +946,11 @@ function parseReceipt(input: unknown, directory: string): SnapshotReceipt {
793
946
  const provenance = field('provenance');
794
947
  if (typeof provenance !== 'object' || provenance === null) return fail('no provenance');
795
948
  const tasks = Reflect.get(provenance, 'tasks');
949
+ const producers = Reflect.get(provenance, 'producers');
950
+ const producerReceipts = field('producerReceipts');
796
951
  const census = field('census');
797
952
  if (!Array.isArray(tasks) || !Array.isArray(census)) return fail('no tasks or census');
953
+ if (!Array.isArray(producers) || !Array.isArray(producerReceipts)) return fail('no producer receipts');
798
954
  return {
799
955
  version: 1,
800
956
  id: text(field('id'), 'id'),
@@ -810,7 +966,17 @@ function parseReceipt(input: unknown, directory: string): SnapshotReceipt {
810
966
  ? { id: text(Reflect.get(task, 'id'), 'task id'), hash: text(Reflect.get(task, 'hash'), 'task hash') }
811
967
  : fail('a task is not an object'),
812
968
  ),
969
+ producers: producers.map((producer: unknown) =>
970
+ typeof producer === 'object' && producer !== null
971
+ ? {
972
+ target: text(Reflect.get(producer, 'target'), 'producer target'),
973
+ basis: text(Reflect.get(producer, 'basis'), 'producer basis'),
974
+ sha256: text(Reflect.get(producer, 'sha256'), 'producer sha256'),
975
+ }
976
+ : fail('a producer is not an object'),
977
+ ),
813
978
  },
979
+ producerReceipts,
814
980
  census: census.map((entry: unknown): CensusEntry => {
815
981
  if (typeof entry !== 'object' || entry === null) return fail('a census entry is not an object');
816
982
  const entryPath = text(Reflect.get(entry, 'path'), 'census path');
@@ -10,9 +10,19 @@ set -euo pipefail
10
10
 
11
11
  root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
12
12
 
13
+ # The devenv profile's bin. Inside this checkout's own devenv shell it is the profile that shell evaluated,
14
+ # DEVENV_PROFILE: an immutable store path, so `bun` there is the one devenv declared for this shell. The
15
+ # checkout's `.devenv/profile` link is a place, not that declaration: every activation of the checkout re-points
16
+ # it, and a fork inherits its source's. Outside a shell of this checkout — a git hook run from a plain terminal
17
+ # or from another checkout's shell — the link is the only name for this checkout's profile.
18
+ profile="$root/tooling/direnv/.devenv/profile"
19
+ if [[ -n "${DEVENV_PROFILE:-}" && "${DEVENV_ROOT:-}" -ef "$root/tooling/direnv" ]]; then
20
+ profile="$DEVENV_PROFILE"
21
+ fi
22
+
13
23
  # Order: most-specific → least-specific.
14
24
  entries=(
15
- "$root/tooling/direnv/.devenv/profile/bin"
25
+ "$profile/bin"
16
26
  "$root/tooling/git-hooks"
17
27
  "$root/tooling"
18
28
  "$root/tooling/node_modules/.bin"
@@ -40,7 +50,10 @@ case "${1:-}" in
40
50
  source "$root/.cowshed/env"
41
51
  fi
42
52
  if [[ -z "${COWSHED_RUNTIME_LINK:-}" ]]; then
43
- export PATH="$HOME/Library/Application Support/dev.cowshed/bin:$PATH"
53
+ # Bash expands `~` to HOME, or with HOME unset to the passwd home of the real uid: a caller that passes
54
+ # only PATH, such as a formatter or a hook under `env -i`, still reaches the installed cowshed.
55
+ home=~
56
+ export PATH="$home/Library/Application Support/dev.cowshed/bin:$PATH"
44
57
  fi
45
58
  printf '%s\n' "$PATH" ;;
46
59
  esac