@smoothbricks/nx-plugin 0.5.4 → 0.5.6

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 (48) hide show
  1. package/README.md +81 -16
  2. package/dist/ensure-built-receipt.d.ts +2 -2
  3. package/dist/ensure-built-receipt.d.ts.map +1 -1
  4. package/dist/ensure-built-receipt.js +7 -2
  5. package/dist/ensure-built-witness.d.ts +12 -1
  6. package/dist/ensure-built-witness.d.ts.map +1 -1
  7. package/dist/ensure-built-witness.js +32 -0
  8. package/dist/ensure-built.d.ts +2 -2
  9. package/dist/ensure-built.d.ts.map +1 -1
  10. package/dist/ensure-built.js +27 -5
  11. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  12. package/dist/executors/bounded-exec/executor.js +48 -11
  13. package/dist/executors/bounded-exec/progress.d.ts +1 -3
  14. package/dist/executors/bounded-exec/progress.d.ts.map +1 -1
  15. package/dist/executors/bounded-exec/progress.js +1 -2
  16. package/dist/executors/bounded-exec/runner-hook.d.ts +2 -0
  17. package/dist/executors/bounded-exec/runner-hook.d.ts.map +1 -0
  18. package/dist/executors/bounded-exec/runner-hook.js +301 -0
  19. package/dist/executors/bounded-exec/runner-lifecycle.d.ts +18 -0
  20. package/dist/executors/bounded-exec/runner-lifecycle.d.ts.map +1 -0
  21. package/dist/executors/bounded-exec/runner-lifecycle.js +92 -0
  22. package/dist/producer-receipts.d.ts +24 -1
  23. package/dist/producer-receipts.d.ts.map +1 -1
  24. package/dist/producer-receipts.js +91 -60
  25. package/dist/runtime-input-policy.d.ts +60 -0
  26. package/dist/runtime-input-policy.d.ts.map +1 -0
  27. package/dist/runtime-input-policy.js +379 -0
  28. package/managed/raw/git-format-staged.yml +16 -3
  29. package/managed/raw/patches/nx@23.2.1.patch +397 -33
  30. package/package.json +7 -2
  31. package/src/ensure-built-receipt.ts +8 -2
  32. package/src/ensure-built-witness.ts +29 -1
  33. package/src/ensure-built.ts +39 -7
  34. package/src/executors/bounded-exec/cargo-progress-host.test.ts +332 -0
  35. package/src/executors/bounded-exec/executor.test.ts +89 -42
  36. package/src/executors/bounded-exec/executor.ts +45 -11
  37. package/src/executors/bounded-exec/progress.test.ts +1 -14
  38. package/src/executors/bounded-exec/progress.ts +2 -5
  39. package/src/executors/bounded-exec/runner-hook.test.ts +193 -0
  40. package/src/executors/bounded-exec/runner-hook.ts +292 -0
  41. package/src/executors/bounded-exec/runner-lifecycle.test.ts +82 -0
  42. package/src/executors/bounded-exec/runner-lifecycle.ts +102 -0
  43. package/src/nx-daemon-start-never.test.ts +137 -0
  44. package/src/producer-receipts.test.ts +99 -0
  45. package/src/producer-receipts.ts +111 -58
  46. package/src/runtime-input-policy.ts +395 -0
  47. package/src/runtime-input.test.ts +160 -3
  48. package/test-timings.json +4 -0
@@ -5,7 +5,7 @@ import { delimiter, dirname, join, resolve } from 'node:path';
5
5
  import typia from 'typia';
6
6
  import { createWorkspaceNxRequire, parseTargetSelector, providerInputProof, selectorTaskId, } from './ensure-built.js';
7
7
  import { captureProducerSource, producerOutputPaths, providerReceipt, receiptNode, } from './ensure-built-receipt.js';
8
- import { censusStart, graphInstallationIdentity, movedNodes, workspaceSnapshot, } from './ensure-built-witness.js';
8
+ import { censusFileHashes, censusStart, graphInstallationCensus, movedNodes, readInstallationCensus, workspaceSnapshot, writeWitness, } from './ensure-built-witness.js';
9
9
  import { graphInputContractIdentity } from './graph-input-contract.js';
10
10
  /**
11
11
  * Where a checkout keeps its producer records, relative to its root: in its own source tree, never in Nx's
@@ -17,6 +17,11 @@ import { graphInputContractIdentity } from './graph-input-contract.js';
17
17
  * is no source or input of the run that publishes it.
18
18
  */
19
19
  export const PRODUCER_RECORDS = join('.cache', 'producer-receipts');
20
+ /**
21
+ * The installation census the pre-task hook took last, in Nx's workspace-data beside the graph witness: a hash source
22
+ * for the next census ({@link installedClosureTool}), never a proof and never part of a receipt.
23
+ */
24
+ const PRODUCER_INSTALLATION_CENSUS = 'producer-installation-census.json';
20
25
  const runs = new Map();
21
26
  function sha(value) {
22
27
  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
@@ -96,6 +101,80 @@ function targetGraph(root, target, projectGraph) {
96
101
  throw new Error(`Invalid declared producer target ${target}`);
97
102
  return createWorkspaceNxRequire(root)('nx/src/tasks-runner/create-task-graph').createTaskGraph(projectGraph, {}, [selector.project], [selector.target], selector.configuration, {}, false);
98
103
  }
104
+ /**
105
+ * The installed closure of Nx, this plugin, TypeScript and the local graph plugins as one producer tool: every node of
106
+ * the installation census, and the module namespace each of its resolutions searched. The census is not proved by a
107
+ * stat pass of its own: each of its nodes is stat-ed again as a tool node, a file whose stamp moved since the census
108
+ * read it is read again, and the capture's stability check refuses a tool node that moves before publication.
109
+ *
110
+ * Its value is a function of the closure's node stamps (device, inode, mode, size, mtime and ctime), not of the moment
111
+ * it is taken. So every node is stat-ed on every call, and that is what makes reuse safe: a file whose stamp is the one
112
+ * the census recorded at `record` read it at keeps that census's hash, so an unchanged closure reads no file bytes,
113
+ * while a file rewritten in place, as a developer-linked package's rebuilt `dist` is with no lockfile or
114
+ * `node_modules` change, moves its ctime and is read again. The tool's nodes take the hash this census read
115
+ * ({@link censusFileHashes}) instead of reading each file a second time: a write landing between two reads could make
116
+ * them disagree.
117
+ */
118
+ export function installedClosureTool(root, nxJson, localInputs, record, resolvePackage, expand, census) {
119
+ let installationMiss = 'unproved installed module/resolution closure';
120
+ performance.mark('producerReceipts:census:start');
121
+ const installation = graphInstallationCensus(root, nxJson, resolvePackage, expand, localInputs ?? { plugins: [], packages: [], identity: '[]' }, (detail) => {
122
+ installationMiss = detail;
123
+ }, readInstallationCensus(record));
124
+ performance.measure('producerReceipts:census', 'producerReceipts:census:start');
125
+ if (installation === null)
126
+ return { ok: false, detail: `Producer installed module/resolution closure is unproved: ${installationMiss}` };
127
+ writeWitness(record, installation);
128
+ const paths = new Set(installation.nodes.map(({ path }) => path));
129
+ const absent = new Set();
130
+ function namespace(path) {
131
+ let stats;
132
+ try {
133
+ stats = lstatSync(path);
134
+ }
135
+ catch (error) {
136
+ if (error instanceof Error && 'code' in error && ['ENOENT', 'ENOTDIR'].includes(String(error.code))) {
137
+ absent.add(path);
138
+ return;
139
+ }
140
+ throw error;
141
+ }
142
+ paths.add(path);
143
+ if (stats.isSymbolicLink())
144
+ paths.add(realpathSync(path));
145
+ if (stats.isDirectory())
146
+ for (const name of readdirSync(path))
147
+ paths.add(join(path, name));
148
+ }
149
+ const resolutions = [];
150
+ for (const [from, name, target] of installation.resolutions) {
151
+ resolutions.push({ from, name, target });
152
+ for (const directory of createRequire(join(from, 'package.json')).resolve.paths(name) ?? []) {
153
+ namespace(directory);
154
+ const candidate = join(directory, name);
155
+ if (existsSync(candidate))
156
+ namespace(candidate);
157
+ else
158
+ absent.add(candidate);
159
+ }
160
+ }
161
+ const recorded = censusFileHashes(installation);
162
+ const nodes = [...paths].sort().map((path) => receiptNode(path, path, census, recorded));
163
+ return {
164
+ ok: true,
165
+ value: {
166
+ kind: 'module',
167
+ name: 'installed-nx-plugin-closure',
168
+ from: root,
169
+ path: root,
170
+ physicalPath: realpathSync(root),
171
+ nodes,
172
+ missing: [...absent].sort(),
173
+ resolutions,
174
+ sha256: sha(nodes),
175
+ },
176
+ };
177
+ }
99
178
  /** Tool resolution is captured in producer scope; readers inspect its recorded filesystem, not their own environment. */
100
179
  function toolsFor(root, nxJson, projectGraph, bases) {
101
180
  try {
@@ -115,67 +194,12 @@ function toolsFor(root, nxJson, projectGraph, bases) {
115
194
  return { ok: false, detail: proof.runtimeSource.detail };
116
195
  needsCargo ||= Object.values(proof.inputs).some((input) => input.runtime.length > 0);
117
196
  }
118
- let installationMiss = 'unproved installed module/resolution closure';
119
- const identity = graphInstallationIdentity(root, nxJson, load('nx/src/utils/package-json').readModulePackageJson, load('nx/src/native').expandOutputs, local ?? { plugins: [], packages: [], identity: '[]' }, (detail) => {
120
- installationMiss = detail;
121
- });
122
- if (identity === null)
123
- return { ok: false, detail: `Producer installed module/resolution closure is unproved: ${installationMiss}` };
124
- const installation = (() => {
125
- const _io0 = input => Array.isArray(input.nodes) && input.nodes.every(elem => "object" === typeof elem && null !== elem && _io1(elem)) && (Array.isArray(input.resolutions) && input.resolutions.every(elem => Array.isArray(elem) && (elem.length === 3 && "string" === typeof elem[0] && "string" === typeof elem[1] && (null === elem[2] || "string" === typeof elem[2])))) && (null === input.localInputs || "string" === typeof input.localInputs);
126
- const _io1 = input => "string" === typeof input.path && "string" === typeof input.stamp;
127
- const __is = input => "object" === typeof input && null !== input && _io0(input);
128
- return input => { input = JSON.parse(input); return __is(input) ? input : null; };
129
- })()(identity);
130
- if (installation === null)
131
- return { ok: false, detail: 'Invalid installed module closure evidence' };
132
197
  const observed = [];
133
198
  const census = { start: censusStart(), observed };
134
- const paths = new Set(installation.nodes.map(({ path }) => path));
135
- const absent = new Set();
136
- function namespace(path) {
137
- let stats;
138
- try {
139
- stats = lstatSync(path);
140
- }
141
- catch (error) {
142
- if (error instanceof Error && 'code' in error && ['ENOENT', 'ENOTDIR'].includes(String(error.code))) {
143
- absent.add(path);
144
- return;
145
- }
146
- throw error;
147
- }
148
- paths.add(path);
149
- if (stats.isSymbolicLink())
150
- paths.add(realpathSync(path));
151
- if (stats.isDirectory())
152
- for (const name of readdirSync(path))
153
- paths.add(join(path, name));
154
- }
155
- const resolutions = [];
156
- for (const [from, name, target] of installation.resolutions) {
157
- resolutions.push({ from, name, target });
158
- for (const directory of createRequire(join(from, 'package.json')).resolve.paths(name) ?? []) {
159
- namespace(directory);
160
- const candidate = join(directory, name);
161
- if (existsSync(candidate))
162
- namespace(candidate);
163
- else
164
- absent.add(candidate);
165
- }
166
- }
167
- const nodes = [...paths].sort().map((path) => receiptNode(path, path, census));
168
- const module = {
169
- kind: 'module',
170
- name: 'installed-nx-plugin-closure',
171
- from: root,
172
- path: root,
173
- physicalPath: realpathSync(root),
174
- nodes,
175
- missing: [...absent].sort(),
176
- resolutions,
177
- sha256: sha(nodes),
178
- };
199
+ const closure = installedClosureTool(root, nxJson, local, join(data, PRODUCER_INSTALLATION_CENSUS), load('nx/src/utils/package-json').readModulePackageJson, load('nx/src/native').expandOutputs, census);
200
+ if (!closure.ok)
201
+ return closure;
202
+ const module = closure.value;
179
203
  const tools = [module];
180
204
  for (const name of ['nx-runtime', 'bun', 'sh', 'git', ...(needsCargo ? ['rustc', 'cargo'] : [])]) {
181
205
  const candidates = name === 'nx-runtime'
@@ -274,19 +298,26 @@ export async function preTasksExecution(options, context) {
274
298
  return;
275
299
  try {
276
300
  const load = createWorkspaceNxRequire(context.workspaceRoot);
301
+ // A hook that can hold a run for minutes names its phases: Nx reports each measure under NX_PERF_LOGGING.
302
+ performance.mark('producerReceipts:graph:start');
277
303
  const projectGraph = await load('nx/src/project-graph/project-graph').createProjectGraphAsync();
304
+ performance.measure('producerReceipts:graph', 'producerReceipts:graph:start');
278
305
  const bases = new Map();
279
306
  for (const target of targets) {
307
+ performance.mark('producerReceipts:source:start');
280
308
  const graph = targetGraph(context.workspaceRoot, target, projectGraph);
281
309
  const outputs = producerOutputPaths(context.workspaceRoot, Object.values(graph.tasks), load('nx/src/native').expandOutputs);
282
310
  const source = captureProducerSource(context.workspaceRoot, outputs);
311
+ performance.measure('producerReceipts:source', 'producerReceipts:source:start');
283
312
  if (!source.ok) {
284
313
  runs.set(context.id, source);
285
314
  return;
286
315
  }
287
316
  bases.set(target, { graph, source: source.value });
288
317
  }
318
+ performance.mark('producerReceipts:tools:start');
289
319
  const tools = toolsFor(context.workspaceRoot, context.nxJsonConfiguration, projectGraph, [...bases.values()]);
320
+ performance.measure('producerReceipts:tools', 'producerReceipts:tools:start');
290
321
  runs.set(context.id, tools.ok
291
322
  ? {
292
323
  ok: true,
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The programs `script` runs by name or path: the program of each simple command, through `env`, `exec`,
3
+ * `command`, `sh -c` and command substitutions, and the command a `runtime-input.sh` input runs. Shell builtins are
4
+ * not programs. A script file a command runs (`sh tooling/x.sh`) is its own source's concern, not read here.
5
+ */
6
+ export declare function commandPrograms(script: string): string[];
7
+ /** Where a runtime input's programs are looked up, and the locations that count as declared rather than the host's. */
8
+ export interface ProgramSearch {
9
+ /** The PATH the input runs with: Nx passes its own environment through. */
10
+ readonly path: string;
11
+ /** The workspace root: its `node_modules/.bin` and tooling are declared by the checkout. */
12
+ readonly root: string;
13
+ /**
14
+ * The user's home. A developer's devenv shell keeps its PATH entries in the checkout direnv loaded (a main
15
+ * checkout's `node_modules/.bin` while a shed is judged) and the user's own tools there; neither is the OS image.
16
+ */
17
+ readonly home: string;
18
+ }
19
+ /** A program a runtime input runs that the workspace does not declare, and why it is refused. */
20
+ export type HostProgram =
21
+ /** PATH finds it outside /nix, the checkout, the home and /bin/sh or /usr/bin/env. */
22
+ {
23
+ readonly program: string;
24
+ readonly refusal: 'host';
25
+ readonly found: string;
26
+ }
27
+ /** Nothing on PATH provides it. */
28
+ | {
29
+ readonly program: string;
30
+ readonly refusal: 'absent';
31
+ }
32
+ /**
33
+ * PATH finds it in the checkout's `node_modules/.bin` as a link to a build output of a package in this checkout. Bun
34
+ * links a workspace package's bin only when its target exists at install time, and a fresh checkout installs before
35
+ * it builds, so the name is absent there while every checkout that built first has it.
36
+ */
37
+ | {
38
+ readonly program: string;
39
+ readonly refusal: 'workspace-bin';
40
+ readonly found: string;
41
+ readonly target: string;
42
+ };
43
+ /**
44
+ * Every program `command` runs that the workspace does not declare: one PATH finds outside the Nix store, the
45
+ * checkout, the home and the guaranteed host paths, one nothing on PATH provides, or one only a workspace package's
46
+ * build output provides. A relative path names a file in the checkout.
47
+ */
48
+ export declare function hostPrograms(command: string, search: ProgramSearch): HostProgram[];
49
+ /** Why `host` is refused, naming where PATH found it and what to run instead. */
50
+ export declare function hostProgramReason(host: HostProgram): string;
51
+ /** The directory under the workspace root where runtime-input.sh retains each failed input. */
52
+ export declare const RUNTIME_INPUT_FAILURES = ".runtime-input-failures";
53
+ /**
54
+ * The report of every failure runtime-input.sh retained under `root` at or after `sinceMs`, oldest first, each headed
55
+ * by its path. Nx 23.2.1 names a failed runtime input only as `invalid utf-8 sequence of 1 bytes from index N` and
56
+ * drops the input's stderr, so a headless run prints these after Nx fails: they name the command, its exit status and
57
+ * its stderr. A record without a report (its evidence could not be written) is named as such.
58
+ */
59
+ export declare function runtimeInputFailureReports(root: string, sinceMs: number): string[];
60
+ //# sourceMappingURL=runtime-input-policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime-input-policy.d.ts","sourceRoot":"","sources":["../src/runtime-input-policy.ts"],"names":[],"mappings":"AAsOA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBxD;AAED,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,iGAAiG;AACjG,MAAM,MAAM,WAAW;AACrB,sFAAsF;AACpF;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAChF,mCAAmC;GACjC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE;AAC1D;;;;GAIG;GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA+CrH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,EAAE,CAiBlF;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAY3D;AAED,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAWhE;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAYlF"}
@@ -0,0 +1,379 @@
1
+ import { accessSync, constants, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
2
+ import { delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path';
3
+ import { RUNTIME_INPUT_SCRIPT } from './runtime-input.js';
4
+ /**
5
+ * What a runtime input may run, and how its failures are read back after Nx refuses it.
6
+ *
7
+ * A runtime input runs wherever Nx hashes: a developer's Mac, a NixOS CI runner, a cowshed sandbox. Only the programs a
8
+ * workspace declares are the same in all of them: devenv's Nix profile and the checkout's own `node_modules`. A
9
+ * program the host's operating system ships is not. macOS ships `shasum` in /usr/bin; it is a Perl script, not
10
+ * coreutils, and no devenv profile provides it (devenv's carries coreutils, `sha256sum` included). An input that named
11
+ * it hashed on every Mac and exited 127 on the NixOS runner, which Nx reported only as
12
+ * `invalid utf-8 sequence of 1 bytes from index 0` (runtime-input.sh says why).
13
+ */
14
+ /** Words a POSIX `sh` runs itself, without a PATH lookup. */
15
+ const SHELL_BUILTINS = new Set([
16
+ '.',
17
+ ':',
18
+ '[',
19
+ 'alias',
20
+ 'break',
21
+ 'cd',
22
+ 'continue',
23
+ 'echo',
24
+ 'eval',
25
+ 'exit',
26
+ 'export',
27
+ 'false',
28
+ 'getopts',
29
+ 'hash',
30
+ 'local',
31
+ 'printf',
32
+ 'pwd',
33
+ 'read',
34
+ 'readonly',
35
+ 'return',
36
+ 'set',
37
+ 'shift',
38
+ 'test',
39
+ 'times',
40
+ 'trap',
41
+ 'true',
42
+ 'type',
43
+ 'ulimit',
44
+ 'umask',
45
+ 'unalias',
46
+ 'unset',
47
+ 'wait',
48
+ ]);
49
+ /** Reserved words that may stand before a command's program. */
50
+ const SHELL_KEYWORDS = new Set([
51
+ '!',
52
+ '{',
53
+ '}',
54
+ 'if',
55
+ 'then',
56
+ 'else',
57
+ 'elif',
58
+ 'fi',
59
+ 'do',
60
+ 'done',
61
+ 'while',
62
+ 'until',
63
+ ]);
64
+ /** Reserved words whose clause names no program (`for name in words`, `case word in`). */
65
+ const CLAUSE_KEYWORDS = new Set(['for', 'case', 'esac', 'in']);
66
+ /** Shells whose `-c` operand is a script of further commands. */
67
+ const SHELLS = new Set(['sh', 'bash']);
68
+ const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
69
+ /** The index of the character that closes the quote opened before `from`, or the end of `text` when none does. */
70
+ function closingQuote(text, from, quote) {
71
+ for (let at = from; at < text.length; at += 1) {
72
+ if (text[at] === '\\' && quote !== "'")
73
+ at += 1;
74
+ else if (text[at] === quote)
75
+ return at;
76
+ }
77
+ return text.length;
78
+ }
79
+ /** The index of the `close` that balances the `open` before `from`, skipping quoted text, or the end of `text`. */
80
+ function closingBracket(text, from, open, close) {
81
+ let depth = 1;
82
+ for (let at = from; at < text.length; at += 1) {
83
+ const character = text[at];
84
+ if (character === '\\')
85
+ at += 1;
86
+ else if (character === "'" || character === '"' || character === '`')
87
+ at = closingQuote(text, at + 1, character);
88
+ else if (character === open)
89
+ depth += 1;
90
+ else if (character === close) {
91
+ depth -= 1;
92
+ if (depth === 0)
93
+ return at;
94
+ }
95
+ }
96
+ return text.length;
97
+ }
98
+ /**
99
+ * The shell tokens of `script`. A command substitution is part of its word, and the programs it runs are appended to
100
+ * `nested`; quoting is removed from the words, which are only inspected, never run.
101
+ */
102
+ function shellTokens(script, nested) {
103
+ const tokens = [];
104
+ let word;
105
+ const flush = () => {
106
+ if (word !== undefined)
107
+ tokens.push({ kind: 'word', text: word });
108
+ word = undefined;
109
+ };
110
+ const append = (text) => {
111
+ word = (word ?? '') + text;
112
+ };
113
+ /** Consumes the expansion starting with `$` or a backquote at `at`; returns the index after it. */
114
+ const expansion = (at) => {
115
+ if (script[at] === '`') {
116
+ const end = closingQuote(script, at + 1, '`');
117
+ nested.push(...commandPrograms(script.slice(at + 1, end)));
118
+ append('`…`');
119
+ return end + 1;
120
+ }
121
+ if (script.startsWith('$((', at)) {
122
+ const end = closingBracket(script, at + 2, '(', ')');
123
+ append(script.slice(at, end + 1));
124
+ return end + 1;
125
+ }
126
+ if (script.startsWith('$(', at)) {
127
+ const end = closingBracket(script, at + 2, '(', ')');
128
+ nested.push(...commandPrograms(script.slice(at + 2, end)));
129
+ append('$(…)');
130
+ return end + 1;
131
+ }
132
+ if (script.startsWith('${', at)) {
133
+ const end = closingBracket(script, at + 2, '{', '}');
134
+ append(script.slice(at, end + 1));
135
+ return end + 1;
136
+ }
137
+ append('$');
138
+ return at + 1;
139
+ };
140
+ let at = 0;
141
+ while (at < script.length) {
142
+ const character = script[at];
143
+ if (character === "'") {
144
+ const end = closingQuote(script, at + 1, "'");
145
+ append(script.slice(at + 1, end));
146
+ at = end + 1;
147
+ }
148
+ else if (character === '"') {
149
+ append('');
150
+ at += 1;
151
+ while (at < script.length && script[at] !== '"') {
152
+ if (script[at] === '\\' && at + 1 < script.length) {
153
+ append('$`"\\\n'.includes(script[at + 1]) ? script[at + 1] : script.slice(at, at + 2));
154
+ at += 2;
155
+ }
156
+ else if (script[at] === '$' || script[at] === '`') {
157
+ at = expansion(at);
158
+ }
159
+ else {
160
+ append(script[at]);
161
+ at += 1;
162
+ }
163
+ }
164
+ at += 1;
165
+ }
166
+ else if (character === '\\') {
167
+ append(script.slice(at + 1, at + 2));
168
+ at += 2;
169
+ }
170
+ else if (character === '$' || character === '`') {
171
+ at = expansion(at);
172
+ }
173
+ else if (character === '#' && word === undefined) {
174
+ at = script.indexOf('\n', at);
175
+ if (at < 0)
176
+ at = script.length;
177
+ }
178
+ else if (character === ' ' || character === '\t') {
179
+ flush();
180
+ at += 1;
181
+ }
182
+ else if (';&|()\n'.includes(character)) {
183
+ flush();
184
+ tokens.push({ kind: 'separator' });
185
+ at += 1;
186
+ }
187
+ else if (character === '<' || character === '>') {
188
+ // A file-descriptor number written against the operator (`2>&1`) is part of it, not a word.
189
+ if (word !== undefined && /^\d+$/.test(word))
190
+ word = undefined;
191
+ flush();
192
+ at += 1;
193
+ while (at < script.length && '<>&|'.includes(script[at]))
194
+ at += 1;
195
+ tokens.push({ kind: 'redirect' });
196
+ }
197
+ else {
198
+ append(character);
199
+ at += 1;
200
+ }
201
+ }
202
+ flush();
203
+ return tokens;
204
+ }
205
+ /** The programs one simple command runs, given its words in order. */
206
+ function simpleCommandPrograms(words) {
207
+ let at = 0;
208
+ while (at < words.length && (SHELL_KEYWORDS.has(words[at]) || ASSIGNMENT.test(words[at])))
209
+ at += 1;
210
+ const program = words[at];
211
+ if (program === undefined || CLAUSE_KEYWORDS.has(program))
212
+ return [];
213
+ const operands = words.slice(at + 1);
214
+ if (program === 'exec')
215
+ return simpleCommandPrograms(operands);
216
+ // `command -v name` looks a name up; `command name` runs it.
217
+ if (program === 'command')
218
+ return operands[0]?.startsWith('-') ? [] : simpleCommandPrograms(operands);
219
+ if (program === 'env') {
220
+ let operand = 0;
221
+ while (operand < operands.length && operands[operand].startsWith('-') && operands[operand] !== '--') {
222
+ operand += operands[operand] === '-u' || operands[operand] === '-C' ? 2 : 1;
223
+ }
224
+ if (operands[operand] === '--')
225
+ operand += 1;
226
+ return [program, ...simpleCommandPrograms(operands.slice(operand))];
227
+ }
228
+ if (SHELLS.has(program)) {
229
+ // The wrapper runs its operands as one command.
230
+ if (operands[0] === RUNTIME_INPUT_SCRIPT)
231
+ return [program, ...simpleCommandPrograms(operands.slice(1))];
232
+ const options = operands.findIndex((operand) => !operand.startsWith('-'));
233
+ const flags = operands.slice(0, options < 0 ? operands.length : options);
234
+ const script = options < 0 ? undefined : operands[options];
235
+ if (script !== undefined && flags.some((flag) => flag !== '--' && !flag.startsWith('--') && flag.includes('c'))) {
236
+ return [program, ...commandPrograms(script)];
237
+ }
238
+ }
239
+ return [program];
240
+ }
241
+ /**
242
+ * The programs `script` runs by name or path: the program of each simple command, through `env`, `exec`,
243
+ * `command`, `sh -c` and command substitutions, and the command a `runtime-input.sh` input runs. Shell builtins are
244
+ * not programs. A script file a command runs (`sh tooling/x.sh`) is its own source's concern, not read here.
245
+ */
246
+ export function commandPrograms(script) {
247
+ const programs = [];
248
+ const nested = [];
249
+ let words = [];
250
+ let redirectTarget = false;
251
+ const end = () => {
252
+ programs.push(...simpleCommandPrograms(words));
253
+ words = [];
254
+ };
255
+ for (const token of shellTokens(script, nested)) {
256
+ if (token.kind === 'separator')
257
+ end();
258
+ else if (token.kind === 'redirect')
259
+ redirectTarget = true;
260
+ else if (redirectTarget)
261
+ redirectTarget = false;
262
+ else
263
+ words.push(token.text);
264
+ }
265
+ end();
266
+ return [...programs, ...nested].filter((program) => !SHELL_BUILTINS.has(program));
267
+ }
268
+ function within(directory, file) {
269
+ const path = relative(directory, file);
270
+ return path !== '' && !path.startsWith('..') && !isAbsolute(path);
271
+ }
272
+ function isExecutableFile(file) {
273
+ try {
274
+ accessSync(file, constants.X_OK);
275
+ return statSync(file).isFile();
276
+ }
277
+ catch (error) {
278
+ if (error instanceof Error && 'code' in error && ['ENOENT', 'ENOTDIR', 'EACCES'].includes(String(error.code))) {
279
+ return false;
280
+ }
281
+ throw error;
282
+ }
283
+ }
284
+ function onPath(program, path) {
285
+ for (const directory of path.split(delimiter)) {
286
+ // An empty entry means the working directory; Nx runs inputs from the root, which a name never resolves into.
287
+ if (directory === '')
288
+ continue;
289
+ const candidate = join(directory, program);
290
+ if (isExecutableFile(candidate))
291
+ return candidate;
292
+ }
293
+ return undefined;
294
+ }
295
+ /**
296
+ * The only host paths every platform guarantees: NixOS keeps exactly these two outside the store, for `#!` lines and
297
+ * for Nx, which runs every runtime input as `sh -c`.
298
+ */
299
+ const GUARANTEED_HOST_PROGRAMS = new Set(['/bin/sh', '/usr/bin/env']);
300
+ /**
301
+ * The build output of a package in this checkout that `found`, a link in the checkout's `node_modules/.bin`, names;
302
+ * undefined for any other file, an installed package's bin included.
303
+ */
304
+ function workspaceBuildOutput(found, root) {
305
+ if (!within(join(root, 'node_modules', '.bin'), found))
306
+ return undefined;
307
+ const physicalRoot = realpathSync(root);
308
+ const target = realpathSync(found);
309
+ return within(physicalRoot, target) && !relative(physicalRoot, target).split(sep).includes('node_modules')
310
+ ? target
311
+ : undefined;
312
+ }
313
+ /**
314
+ * Every program `command` runs that the workspace does not declare: one PATH finds outside the Nix store, the
315
+ * checkout, the home and the guaranteed host paths, one nothing on PATH provides, or one only a workspace package's
316
+ * build output provides. A relative path names a file in the checkout.
317
+ */
318
+ export function hostPrograms(command, search) {
319
+ const declared = (file) => file.startsWith('/nix/') ||
320
+ GUARANTEED_HOST_PROGRAMS.has(file) ||
321
+ within(search.root, file) ||
322
+ within(search.home, file);
323
+ return [...new Set(commandPrograms(command))].flatMap((program) => {
324
+ if (program.includes('/')) {
325
+ const found = resolve(search.root, program);
326
+ return declared(found) ? [] : [{ program, refusal: 'host', found }];
327
+ }
328
+ const found = onPath(program, search.path);
329
+ if (found === undefined)
330
+ return [{ program, refusal: 'absent' }];
331
+ if (!declared(found))
332
+ return [{ program, refusal: 'host', found }];
333
+ const target = workspaceBuildOutput(found, search.root);
334
+ return target === undefined ? [] : [{ program, refusal: 'workspace-bin', found, target }];
335
+ });
336
+ }
337
+ /** Why `host` is refused, naming where PATH found it and what to run instead. */
338
+ export function hostProgramReason(host) {
339
+ switch (host.refusal) {
340
+ case 'host':
341
+ return `PATH finds ${host.program} at ${host.found}, a host program no devenv profile declares`;
342
+ case 'absent':
343
+ return `nothing on PATH provides ${host.program}`;
344
+ case 'workspace-bin':
345
+ return (`PATH finds ${host.program} at ${host.found}, a link to this checkout's build output ${host.target}, ` +
346
+ 'which an install that runs before the build does not create; run that file with node or bun instead');
347
+ }
348
+ }
349
+ /** The directory under the workspace root where runtime-input.sh retains each failed input. */
350
+ export const RUNTIME_INPUT_FAILURES = '.runtime-input-failures';
351
+ function absentAsUndefined(read) {
352
+ try {
353
+ return read();
354
+ }
355
+ catch (error) {
356
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
357
+ return undefined;
358
+ throw error;
359
+ }
360
+ }
361
+ /**
362
+ * The report of every failure runtime-input.sh retained under `root` at or after `sinceMs`, oldest first, each headed
363
+ * by its path. Nx 23.2.1 names a failed runtime input only as `invalid utf-8 sequence of 1 bytes from index N` and
364
+ * drops the input's stderr, so a headless run prints these after Nx fails: they name the command, its exit status and
365
+ * its stderr. A record without a report (its evidence could not be written) is named as such.
366
+ */
367
+ export function runtimeInputFailureReports(root, sinceMs) {
368
+ const directory = join(root, RUNTIME_INPUT_FAILURES);
369
+ return (absentAsUndefined(() => readdirSync(directory)) ?? [])
370
+ .map((name) => join(directory, name))
371
+ .map((record) => ({ record, modifiedMs: statSync(record).mtimeMs }))
372
+ .filter(({ modifiedMs }) => modifiedMs >= sinceMs)
373
+ .sort((left, right) => left.modifiedMs - right.modifiedMs)
374
+ .map(({ record }) => {
375
+ const report = join(record, 'report');
376
+ const text = absentAsUndefined(() => readFileSync(report, 'utf8'));
377
+ return text === undefined ? `${record}: no report; its evidence is incomplete\n` : `${report}:\n${text}`;
378
+ });
379
+ }
@@ -9,9 +9,16 @@ formatters:
9
9
  - '!.*' # Exclude hidden files
10
10
 
11
11
  # Biome for JS/TS family (including CommonJS/CTS and ESM .mjs/.mts)
12
- # Biome check --fix silently succeeds on unparsable stdin; format must refuse it.
13
- biome:
14
- command: "biome format --files-ignore-unknown=true --use-editorconfig=true '--stdin-file-path={}'"
12
+ # At commit it may rewrite exactly: formatting, import order (assist/source/organizeImports) and string
13
+ # concatenation to template literals (lint/style/useTemplate, an unsafe fix, so --unsafe with --only).
14
+ # Those two are the land gate's autofixable refusals; every other rule stays a lint finding.
15
+ # Biome check --write silently passes unparsable stdin through; the final biome format refuses it,
16
+ # and the pipeline's status is that format's.
17
+ biome-scripts:
18
+ command:
19
+ "biome check --write --unsafe --files-ignore-unknown=true --use-editorconfig=true
20
+ --only=assist/source/organizeImports --only=lint/style/useTemplate '--stdin-file-path={}' | biome format
21
+ --files-ignore-unknown=true --use-editorconfig=true '--stdin-file-path={}'"
15
22
  patterns:
16
23
  - '*.js'
17
24
  - '*.cjs'
@@ -21,6 +28,12 @@ formatters:
21
28
  - '*.mts'
22
29
  - '*.jsx'
23
30
  - '*.tsx'
31
+
32
+ # Biome for data and markup. smoo's JSON writer runs this exact command (biomeHookArguments), so a
33
+ # file it writes is a fixed point of the hook; a test pins the two together.
34
+ biome:
35
+ command: "biome format --files-ignore-unknown=true --use-editorconfig=true '--stdin-file-path={}'"
36
+ patterns:
24
37
  - '*.json'
25
38
  - '*.jsonc'
26
39
  - '*.html'