@smoothbricks/nx-plugin 0.6.1 → 0.6.3-0

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 (104) hide show
  1. package/README.md +264 -55
  2. package/dist/.build-inputs.json +21 -15
  3. package/dist/bin/smoo-nx-publish.d.ts +3 -0
  4. package/dist/bin/smoo-nx-publish.d.ts.map +1 -0
  5. package/dist/bin/smoo-nx-publish.js +3 -0
  6. package/dist/cargo-retention-hook.d.ts +14 -3
  7. package/dist/cargo-retention-hook.d.ts.map +1 -1
  8. package/dist/cargo-retention-hook.js +25 -8
  9. package/dist/eslint-file-set.d.ts +4 -1
  10. package/dist/eslint-file-set.d.ts.map +1 -1
  11. package/dist/eslint-sources.d.ts +25 -0
  12. package/dist/eslint-sources.d.ts.map +1 -0
  13. package/dist/eslint-sources.js +99 -0
  14. package/dist/executors/all-verdicts/executor.d.ts +2 -1
  15. package/dist/executors/all-verdicts/executor.d.ts.map +1 -1
  16. package/dist/executors/all-verdicts/executor.js +48 -2
  17. package/dist/executors/all-verdicts/schema.d.ts +13 -0
  18. package/dist/executors/all-verdicts/schema.d.ts.map +1 -1
  19. package/dist/executors/all-verdicts/schema.js +7 -0
  20. package/dist/executors/bounded-exec/bounds.d.ts +57 -8
  21. package/dist/executors/bounded-exec/bounds.d.ts.map +1 -1
  22. package/dist/executors/bounded-exec/bounds.js +100 -11
  23. package/dist/executors/bounded-exec/executor.d.ts +2 -1
  24. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  25. package/dist/executors/bounded-exec/executor.js +270 -27
  26. package/dist/executors/bounded-exec/hang-diagnostics.d.ts +2 -0
  27. package/dist/executors/bounded-exec/hang-diagnostics.d.ts.map +1 -1
  28. package/dist/executors/bounded-exec/hang-diagnostics.js +27 -3
  29. package/dist/executors/bounded-exec/mbx-pool.d.ts +20 -3
  30. package/dist/executors/bounded-exec/mbx-pool.d.ts.map +1 -1
  31. package/dist/executors/bounded-exec/mbx-pool.js +84 -4
  32. package/dist/executors/bounded-exec/mbx-queue.d.ts +30 -0
  33. package/dist/executors/bounded-exec/mbx-queue.d.ts.map +1 -0
  34. package/dist/executors/bounded-exec/mbx-queue.js +229 -0
  35. package/dist/executors/bounded-exec/progress.d.ts +9 -2
  36. package/dist/executors/bounded-exec/progress.d.ts.map +1 -1
  37. package/dist/executors/bounded-exec/progress.js +148 -22
  38. package/dist/executors/bounded-exec/test-result-writer.d.ts +30 -0
  39. package/dist/executors/bounded-exec/test-result-writer.d.ts.map +1 -0
  40. package/dist/executors/bounded-exec/test-result-writer.js +126 -0
  41. package/dist/executors/bounded-exec/test-results.d.ts +33 -0
  42. package/dist/executors/bounded-exec/test-results.d.ts.map +1 -0
  43. package/dist/executors/bounded-exec/test-results.js +33 -0
  44. package/dist/executors/bounded-exec/verdict.d.ts +20 -2
  45. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  46. package/dist/executors/bounded-exec/verdict.js +102 -4
  47. package/dist/index.d.ts +3 -2
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +67 -65
  50. package/dist/managed-files/files.d.ts.map +1 -1
  51. package/dist/managed-files/files.js +6 -0
  52. package/dist/nx-publish.d.ts +24 -0
  53. package/dist/nx-publish.d.ts.map +1 -0
  54. package/dist/nx-publish.js +150 -0
  55. package/dist/runtime-input-policy.d.ts +14 -0
  56. package/dist/runtime-input-policy.d.ts.map +1 -1
  57. package/dist/runtime-input-policy.js +1 -1
  58. package/dist/tool-bins.d.ts +6 -8
  59. package/dist/tool-bins.d.ts.map +1 -1
  60. package/dist/tool-bins.js +7 -5
  61. package/dist/workspace-index.d.ts +7 -0
  62. package/dist/workspace-index.d.ts.map +1 -1
  63. package/dist/workspace-index.js +11 -0
  64. package/executors.json +1 -1
  65. package/managed/raw/envrc +15 -0
  66. package/managed/raw/patches/ttsc@0.34.1.patch +75 -0
  67. package/managed/raw/tooling/devenv +1 -2
  68. package/managed/raw/tooling/direnv/developer-links.ts +15 -1
  69. package/managed/raw/tooling/direnv/devenv.smoo.nix +45 -13
  70. package/managed/raw/tooling/direnv/github-actions-bootstrap.sh +20 -10
  71. package/managed/raw/tooling/direnv/linked-snapshots.ts +50 -13
  72. package/managed/raw/tooling/direnv/setup-environment.ts +36 -9
  73. package/managed/raw/tooling/direnv/ttsc-env.sh +8 -6
  74. package/managed/raw/tooling/git-hooks/pre-push.sh +4 -1
  75. package/managed/raw/tooling/git-reword-commit +151 -0
  76. package/managed/templates/github/actions/cache-node-modules/action.yml +1 -1
  77. package/managed/templates/github/actions/cache-ttsc-plugins/action.yml +12 -11
  78. package/package.json +226 -10
  79. package/runtime/nx-publish/cache_adapter.js +45 -0
  80. package/runtime/nx-publish/nx_publish.js +60 -0
  81. package/runtime-input.sh +12 -3
  82. package/src/bin/smoo-nx-publish.ts +4 -0
  83. package/src/cargo-retention-hook.ts +28 -11
  84. package/src/eslint-file-set.ts +4 -1
  85. package/src/eslint-sources.ts +134 -0
  86. package/src/executors/all-verdicts/executor.ts +58 -3
  87. package/src/executors/all-verdicts/schema.json +4 -0
  88. package/src/executors/all-verdicts/schema.ts +14 -0
  89. package/src/executors/bounded-exec/bounds.ts +132 -15
  90. package/src/executors/bounded-exec/executor.ts +303 -27
  91. package/src/executors/bounded-exec/hang-diagnostics.ts +31 -3
  92. package/src/executors/bounded-exec/mbx-pool.ts +82 -5
  93. package/src/executors/bounded-exec/mbx-queue.ts +170 -0
  94. package/src/executors/bounded-exec/progress.ts +168 -15
  95. package/src/executors/bounded-exec/test-result-writer.ts +152 -0
  96. package/src/executors/bounded-exec/test-results.ts +39 -0
  97. package/src/executors/bounded-exec/verdict.ts +108 -5
  98. package/src/index.ts +74 -70
  99. package/src/managed-files/files.ts +6 -0
  100. package/src/nx-publish.ts +157 -0
  101. package/src/runtime-input-policy.ts +1 -1
  102. package/src/tool-bins.ts +13 -9
  103. package/src/workspace-index.ts +12 -0
  104. package/test-timings.json +8 -2
@@ -0,0 +1,60 @@
1
+ // A land's publish (05_gateway.md "`/nx/v1/cache/{hash}`"): after the gate passed, every task result
2
+ // the gate's Nx runs named is stored to the project's Nx cache from this checkout's own cache, as
3
+ // plain PUTs by the stock native client. Prefixed once by cache_adapter::script.
4
+ // Usage: node - <absolute Nx root> <JSON array of task hashes>; answers one JSON line on stdout.
5
+ const answer = process.stdout.write.bind(process.stdout);
6
+ process.stdout.write = process.stderr.write.bind(process.stderr);
7
+ const fs = require('node:fs');
8
+ const path = require('node:path');
9
+ const [root, hashesJson] = process.argv.slice(2);
10
+ if (!root || !path.isAbsolute(root) || hashesJson === undefined) {
11
+ throw new Error('usage: node - <absolute Nx root> <JSON array of task hashes>');
12
+ }
13
+ const hashes = JSON.parse(hashesJson);
14
+ if (!Array.isArray(hashes) || new Set(hashes).size !== hashes.length) {
15
+ throw new Error('the land must name distinct task hashes');
16
+ }
17
+ // One validated Nx task key (05_gateway.md): the charset the gateway's route and the store accept.
18
+ for (const hash of hashes) {
19
+ if (typeof hash !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(hash)) {
20
+ throw new Error(`invalid Nx task hash ${JSON.stringify(hash)}`);
21
+ }
22
+ }
23
+ const server = process.env.NX_SELF_HOSTED_REMOTE_CACHE_SERVER;
24
+ if (!server) throw new Error('NX_SELF_HOSTED_REMOTE_CACHE_SERVER names no project Nx cache');
25
+
26
+ async function publish() {
27
+ const { requireNx, cacheDir, getLocal } = openNxCache(root);
28
+ const { HttpRemoteCache } = requireNx('nx/src/native');
29
+ const remote = new HttpRemoteCache();
30
+ let published = 0;
31
+ let existing = 0;
32
+ let skipped = 0;
33
+ for (const hash of hashes) {
34
+ const result = getLocal(hash);
35
+ // A task Nx does not cache, or one that failed, has no complete entry to share.
36
+ if (result?.code !== 0 || !fs.statSync(result.outputsPath, { throwIfNoEntry: false })?.isDirectory()) {
37
+ skipped += 1;
38
+ continue;
39
+ }
40
+ if (await remote.store(hash, cacheDir, result.terminalOutput ?? '', 0)) {
41
+ published += 1;
42
+ continue;
43
+ }
44
+ // The native store answers false for an existing key (409) and for a refusal: tell them apart.
45
+ const response = await fetch(`${server}/v1/cache/${hash}`);
46
+ await response.body?.cancel();
47
+ if (response.status !== 200) {
48
+ throw new Error(`task ${hash} was not stored, and the project cache answers GET ${response.status}`);
49
+ }
50
+ existing += 1;
51
+ }
52
+ return { published, existing, skipped };
53
+ }
54
+ publish().then(
55
+ (result) => answer(`${JSON.stringify(result)}\n`),
56
+ (error) => {
57
+ console.error(error);
58
+ process.exitCode = 1;
59
+ },
60
+ );
package/runtime-input.sh CHANGED
@@ -78,9 +78,18 @@ if record=$(umask 077; mkdir -p "$PWD/.runtime-input-failures" &&
78
78
  cat "$record/stdout"
79
79
  } >"$record/report"; then
80
80
  printf '\nruntime input exited %s: %s; evidence: %s/report\n' "$status" "$*" "$record" >&2
81
- # A detached daemon may have no terminal. Preserve that error too, rather
82
- # than sending it into Nx's discarded stderr or swallowing it.
83
- (exec 4>/dev/tty && cat "$record/report" >&4) 2>"$record/terminal-error"
81
+ # Nx discards this stderr, so a controlling terminal is the one live display
82
+ # of the report. Nx's daemon has none (ENXIO) and cowshed's sandbox denies
83
+ # it (EPERM). Having no terminal is no failure of the input: the shell's
84
+ # refusal of the open joins the notice above on stderr, and the record
85
+ # gains nothing. `command` keeps that refusal from exiting the shell. A
86
+ # write that fails on a terminal that did open is retained in the record.
87
+ if command exec 4>/dev/tty; then
88
+ if ! failure=$(cat "$record/report" 2>&1 >&4); then
89
+ printf '%s\n' "$failure" >"$record/terminal-error"
90
+ fi
91
+ exec 4>&-
92
+ fi
84
93
  else
85
94
  printf '\nruntime input exited %s: %s; evidence incomplete: %s; stderr capture: %s\n' \
86
95
  "$status" "$*" "$record" "$diagnostic" >&2
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { runNxPublish } from '../nx-publish.js';
3
+
4
+ process.exitCode = await runNxPublish(process.argv.slice(2));
@@ -1,13 +1,14 @@
1
1
  import { join, relative } from 'node:path';
2
2
  import {
3
- describeRetention,
4
3
  describeRetentionError,
4
+ describeRetentionStart,
5
5
  type Result,
6
6
  type RetentionError,
7
- type RetentionReport,
7
+ type RetentionStart,
8
8
  refusedAnywhere,
9
- retainCargoWorkspace,
9
+ startRetentionPass,
10
10
  } from '@smoothbricks/cargo-retain';
11
+ import { launchNodeCli } from '@smoothbricks/cargo-retain/launch-node';
11
12
  import { nodeLocks } from '@smoothbricks/cargo-retain/locks-node';
12
13
  import { logger, type ProjectGraph, readCachedProjectGraph } from 'nx/src/devkit-exports.js';
13
14
  import type { PostTasksExecutionContext } from 'nx/src/project-graph/plugins/public-api.js';
@@ -40,13 +41,28 @@ function ran(status: TaskStatus): boolean {
40
41
  */
41
42
  export const CARGO_PRODUCER_METADATA = { cargoProducer: true } as const;
42
43
 
44
+ /**
45
+ * Whether the run's environment is an mbx project's canonical one, which names the shared store beside mbx-managed
46
+ * target views (specs/cowshed/11_shell.md, "Canonical mbx environment"). Such a project's targets are mbx's to collect,
47
+ * so the plugin retains and purges nothing in them (specs/cowshed/16_build_volumes.md, "Migration" step 4).
48
+ */
49
+ export function mbxManagesTargets(environment: Readonly<NodeJS.ProcessEnv>): boolean {
50
+ return Boolean(environment.MBX_CACHE_DIR) && environment.MBX_TARGET_VIEWS === '1';
51
+ }
52
+
43
53
  /**
44
54
  * After a run that executed a Cargo producer task ({@link CARGO_PRODUCER_METADATA}), check whether
45
- * each Cargo workspace is due for its daily maintenance. A successful receipt schedules only;
46
- * every due pass reads the current graph under Cargo's locks and is awaited by this Nx process.
47
- * Maintenance never fails the run it follows: every outcome, a refused or busy pass included, is only reported.
55
+ * each Cargo workspace is due for its daily maintenance, and start each due pass in a process of its own
56
+ * (`startRetentionPass`). Nx awaits this hook, inside its daemon when one serves the run, so the pass never runs here:
57
+ * its unlinks are synchronous, and one freeing a large trash on a loaded volume held a daemon, and every client waiting
58
+ * on it, for more than thirty minutes. Here only the gate answers (not due, busy, refused); the started pass reads the
59
+ * current graph under Cargo's locks and records its outcome in the target's receipt, and neither this process nor its
60
+ * exit waits on it. A successful receipt schedules only.
61
+ * Maintenance never fails the run it follows: every outcome, a refused or busy pass included, is only reported. In an
62
+ * mbx project ({@link mbxManagesTargets}) it does nothing.
48
63
  */
49
64
  export async function postTasksExecution(_options: unknown, context: PostTasksExecutionContext): Promise<void> {
65
+ if (mbxManagesTargets(process.env)) return;
50
66
  const executed = Object.values(context.taskResults).filter(({ status }) => ran(status));
51
67
  if (executed.length === 0) return;
52
68
  let graph: ProjectGraph;
@@ -69,9 +85,9 @@ export async function postTasksExecution(_options: unknown, context: PostTasksEx
69
85
  if (done.some((workspaceRoot) => !relative(workspaceRoot, root).startsWith('..'))) continue;
70
86
  const started = performance.now();
71
87
  const cpu = process.cpuUsage();
72
- let result: Result<RetentionReport, RetentionError>;
88
+ let result: Result<RetentionStart, RetentionError>;
73
89
  try {
74
- result = await retainCargoWorkspace(root, { apply: true, automatic: true, now: Date.now() }, nodeLocks);
90
+ result = await startRetentionPass(root, Date.now(), nodeLocks, launchNodeCli);
75
91
  } catch (error) {
76
92
  // Maintenance never fails the run it follows: say what escaped, then go on to the next workspace.
77
93
  const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
@@ -86,9 +102,10 @@ export async function postTasksExecution(_options: unknown, context: PostTasksEx
86
102
  logger.warn(`Cargo retention for ${root}: ${describeRetentionError(result.error)}`);
87
103
  continue;
88
104
  }
89
- done.push(result.value.workspaceRoot);
90
- const line = describeRetention(result.value);
91
- if (refusedAnywhere(result.value)) logger.warn(line);
105
+ const start = result.value;
106
+ done.push(start.kind === 'answered' ? start.report.workspaceRoot : start.workspaceRoot);
107
+ const line = describeRetentionStart(start);
108
+ if (start.kind === 'answered' && refusedAnywhere(start.report)) logger.warn(line);
92
109
  else logger.info(line);
93
110
  }
94
111
  }
@@ -1,6 +1,9 @@
1
1
  import typia from 'typia';
2
2
 
3
- /** The exact command and sources source-aware ESLint inference retains for cache inspectors. */
3
+ /**
4
+ * What source-aware ESLint inference retains for cache inspectors: the command, which names no file, and the sources
5
+ * the graph that wrote it resolved. The run reads the sources it lints when it starts.
6
+ */
4
7
  export interface EslintFileSet {
5
8
  readonly command: string;
6
9
  readonly files: readonly string[];
@@ -0,0 +1,134 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { dirname, isAbsolute, join, posix, relative, sep } from 'node:path';
3
+ import {
4
+ type ParsedCommandLine,
5
+ parseJsonConfigFileContent,
6
+ readConfigFile,
7
+ sys as typescriptSys,
8
+ WatchDirectoryFlags,
9
+ } from 'typescript';
10
+ import { ESLINT_SOURCES_TOKEN } from './executors/all-verdicts/schema.js';
11
+ import { shellWord } from './runtime-input.js';
12
+ import { isNonSourceDirectory } from './source-directories.js';
13
+ import { freshIndexedFiles } from './workspace-index.js';
14
+
15
+ /** The module kinds ESLint is handed. */
16
+ const SOURCE_KINDS = '{js,jsx,cjs,mjs,ts,tsx,cts,mts}';
17
+
18
+ /** Every JavaScript and TypeScript module kind ESLint is handed, as one glob. */
19
+ export const ESLINT_SOURCES_GLOB = `**/*.${SOURCE_KINDS}`;
20
+
21
+ /** TypeScript's code for a declaration that selects no file: a test program of none, not a broken one. */
22
+ const NO_INPUTS_FOUND = 18003;
23
+
24
+ /** What ESLint lints for one project, and the lint inputs that key its verdict beyond the project's own files. */
25
+ export interface EslintSources {
26
+ /** The files ESLint is handed, workspace-relative and sorted. */
27
+ readonly files: readonly string[];
28
+ /**
29
+ * The test declaration, then a glob for each directory its include patterns walk and each other program file by
30
+ * name: a file the program gains later is keyed without the graph naming it.
31
+ */
32
+ readonly inputs: readonly string[];
33
+ }
34
+
35
+ /**
36
+ * Read a tsconfig with this plugin's own TypeScript. `@nx/js`'s readTsConfig does an
37
+ * undeclared `require('typescript')` resolved from its own location: where that lands on the
38
+ * TypeScript 7 native package (whose entry exports only its version), `sys` is undefined and
39
+ * graph construction dies reading `sys.readFile`. The plugin declares TypeScript 6, whose
40
+ * `sys` this uses, so the resolution is the one this package's manifest promises.
41
+ */
42
+ function readTestTsConfig(testConfig: string): ParsedCommandLine {
43
+ const readResult = readConfigFile(testConfig, typescriptSys.readFile);
44
+ return parseJsonConfigFileContent(readResult.config, typescriptSys, dirname(testConfig));
45
+ }
46
+
47
+ /** The workspace-relative POSIX path of `absolute`, or null when it lies outside the workspace. */
48
+ function insideWorkspace(workspaceRoot: string, absolute: string): string | null {
49
+ const path = relative(workspaceRoot, absolute).split(sep).join('/');
50
+ return path === '..' || path.startsWith('../') || isAbsolute(path) ? null : path;
51
+ }
52
+
53
+ /** A directory a test declaration's include patterns walk, workspace-relative ('' is the workspace root). */
54
+ interface WalkedDirectory {
55
+ readonly directory: string;
56
+ readonly recursive: boolean;
57
+ }
58
+
59
+ function walks({ directory, recursive }: WalkedDirectory, path: string): boolean {
60
+ const within = directory === '' ? path : path.startsWith(`${directory}/`) ? path.slice(directory.length + 1) : null;
61
+ return within !== null && (recursive || !within.includes('/'));
62
+ }
63
+
64
+ function walkedInput({ directory, recursive }: WalkedDirectory): string {
65
+ return `{workspaceRoot}/${directory === '' ? '' : `${directory}/`}${recursive ? '**/' : ''}*.${SOURCE_KINDS}`;
66
+ }
67
+
68
+ /**
69
+ * What ESLint lints for `projectRoot`, out of `indexed`, the JavaScript and TypeScript modules of an Nx workspace file
70
+ * index (.gitignore and .nxignore applied): its `src` files, and the files its `tsconfig.test.json` declares wherever
71
+ * they live. Only an indexed module counts: an ignored one is build output a fresh checkout lacks, and a JSON file is
72
+ * not ESLint's. Which index `indexed` comes from is the caller's: the graph's to describe a project, the filesystem's
73
+ * now to run ESLint on it.
74
+ */
75
+ export function eslintSources(workspaceRoot: string, projectRoot: string, indexed: ReadonlySet<string>): EslintSources {
76
+ const files = new Set<string>();
77
+ const sourcePrefix = projectRoot === '.' ? 'src/' : `${posix.normalize(projectRoot)}/src/`;
78
+ for (const path of indexed) {
79
+ if (
80
+ path.startsWith(sourcePrefix) &&
81
+ !path.slice(sourcePrefix.length).split('/').slice(0, -1).some(isNonSourceDirectory)
82
+ ) {
83
+ files.add(path);
84
+ }
85
+ }
86
+ const inputs: string[] = [];
87
+ const testConfig = join(workspaceRoot, projectRoot, 'tsconfig.test.json');
88
+ if (existsSync(testConfig)) {
89
+ // A test program can live anywhere the declaration selects, not just src.
90
+ // Use the compiler's file set and the existing declaration-chain hasher,
91
+ // so inherited includes and files outside this project keep their keys.
92
+ const program = readTestTsConfig(testConfig);
93
+ const errors = program.errors.filter(({ code }) => code !== NO_INPUTS_FOUND);
94
+ if (errors.length > 0) {
95
+ throw new Error(
96
+ `${testConfig}: ${errors.map(({ code, messageText }) => `TS${code}: ${JSON.stringify(messageText)}`).join('; ')}`,
97
+ );
98
+ }
99
+ inputs.push('{projectRoot}/tsconfig.test.json');
100
+ // The directories the include patterns walk are keyed as globs, so a file added to one is keyed the moment it
101
+ // exists, and the compiler's own set of walked directories says which they are.
102
+ const walked: WalkedDirectory[] = [];
103
+ for (const [absolute, flags] of Object.entries(program.wildcardDirectories ?? {})) {
104
+ const directory = insideWorkspace(workspaceRoot, absolute);
105
+ if (directory !== null && !directory.split('/').some(isNonSourceDirectory)) {
106
+ walked.push({ directory, recursive: (flags & WatchDirectoryFlags.Recursive) !== 0 });
107
+ }
108
+ }
109
+ inputs.push(...walked.map(walkedInput).sort());
110
+ const named: string[] = [];
111
+ for (const absolute of program.fileNames) {
112
+ const path = insideWorkspace(workspaceRoot, absolute);
113
+ if (path === null) {
114
+ throw new Error(`${testConfig}: test source ${absolute} is outside the workspace and cannot be hashed`);
115
+ }
116
+ if (!indexed.has(path) || path.split('/').some(isNonSourceDirectory)) continue;
117
+ files.add(path);
118
+ if (!walked.some((entry) => walks(entry, path))) named.push(`{workspaceRoot}/${path}`);
119
+ }
120
+ inputs.push(...named.sort());
121
+ }
122
+ return { files: [...files].sort(), inputs: [...new Set(inputs)] };
123
+ }
124
+
125
+ /** What ESLint lints for `projectRoot` as the filesystem holds it now, through a fresh workspace file index. */
126
+ export function freshEslintSources(workspaceRoot: string, projectRoot: string): EslintSources {
127
+ return eslintSources(workspaceRoot, projectRoot, new Set(freshIndexedFiles(workspaceRoot, [ESLINT_SOURCES_GLOB])));
128
+ }
129
+
130
+ /** `command` with each {@link ESLINT_SOURCES_TOKEN} replaced by the shell words of `files`. */
131
+ export function expandEslintSources(command: string, files: readonly string[]): string {
132
+ const words = files.map((file) => shellWord(file)).join(' ');
133
+ return command.replaceAll(ESLINT_SOURCES_TOKEN, () => words);
134
+ }
@@ -2,7 +2,7 @@ import { type ChildProcessByStdio, spawn } from 'node:child_process';
2
2
  import { resolve } from 'node:path';
3
3
  import type { Readable } from 'node:stream';
4
4
 
5
- import type { AllVerdictsOptions } from './schema.js';
5
+ import { type AllVerdictsOptions, ESLINT_SOURCES_TOKEN } from './schema.js';
6
6
 
7
7
  /**
8
8
  * A command's verdict. Only a command that exited reached one. A command a signal ended, one that never started and
@@ -113,12 +113,44 @@ function judge(run: Run, cwd: string): Promise<Verdict> {
113
113
  });
114
114
  }
115
115
 
116
+ /** A command as it will run: the text the shell gets, or why it needs no run. */
117
+ interface Planned {
118
+ readonly command: string;
119
+ readonly noRun?: string;
120
+ }
121
+
122
+ /**
123
+ * The commands as they run now. A command that names {@link ESLINT_SOURCES_TOKEN} gets the files ESLint is handed for
124
+ * `eslintProjectRoot` as the filesystem holds them at this moment, read through a fresh workspace file index: a graph the
125
+ * daemon serves past a deletion or an addition its watcher never reported still lints the files that exist. A project
126
+ * with none has nothing to lint, and no ESLint process starts for it.
127
+ */
128
+ async function planCommands(options: AllVerdictsOptions, root: string): Promise<readonly Planned[]> {
129
+ if (!options.commands.some((command) => command.includes(ESLINT_SOURCES_TOKEN))) {
130
+ return options.commands.map((command) => ({ command }));
131
+ }
132
+ const projectRoot = options.eslintProjectRoot;
133
+ if (projectRoot === undefined) {
134
+ throw new Error(
135
+ `a command names ${ESLINT_SOURCES_TOKEN}, and the target names no eslintProjectRoot to resolve it for`,
136
+ );
137
+ }
138
+ const { expandEslintSources, freshEslintSources } = await import('../../eslint-sources.js');
139
+ const { files } = freshEslintSources(root, projectRoot);
140
+ return options.commands.map((command): Planned => {
141
+ if (!command.includes(ESLINT_SOURCES_TOKEN)) return { command };
142
+ if (files.length === 0) return { command, noRun: `no ESLint sources under ${projectRoot}: nothing to lint` };
143
+ return { command: expandEslintSources(command, files) };
144
+ });
145
+ }
146
+
116
147
  /**
117
148
  * Starts every command at once and lets each reach its own verdict. Nx's run-commands cannot: in parallel it terminates
118
149
  * the other commands once one fails, and serially it never starts the ones after a failure, so one tool's errors hide
119
150
  * another's until a later run. Here no command ends another. Each command's output prints as one block when it closes,
120
151
  * then every command's verdict. A signal to the run ends every command's process group, reports each command still
121
152
  * running UNJUDGED, and ends the run by the same signal. The run succeeds only when every command passed.
153
+ * A command that names the ESLint sources placeholder is resolved first, and the verdicts name it as it ran.
122
154
  */
123
155
  export default async function allVerdictsExecutor(
124
156
  options: AllVerdictsOptions,
@@ -129,7 +161,23 @@ export default async function allVerdictsExecutor(
129
161
  return { success: false };
130
162
  }
131
163
  const cwd = resolve(context.root, options.cwd);
132
- const runs: Run[] = options.commands.map((command) => ({ command, output: [], pid: undefined, verdict: null }));
164
+ let planned: readonly Planned[];
165
+ try {
166
+ planned = await planCommands(options, context.root);
167
+ } catch (error) {
168
+ process.stderr.write(
169
+ `all-verdicts: cannot resolve the commands to run: ${error instanceof Error ? error.message : String(error)}\n`,
170
+ );
171
+ return { success: false };
172
+ }
173
+ const runs = planned.map(
174
+ ({ command, noRun }): Run => ({
175
+ command,
176
+ output: noRun === undefined ? [] : [`${noRun}\n`],
177
+ pid: undefined,
178
+ verdict: noRun === undefined ? null : { kind: 'pass' },
179
+ }),
180
+ );
133
181
  const onExit = (): void => {
134
182
  for (const run of runs) {
135
183
  if (run.verdict === null && run.pid !== undefined) signalCommand(run.pid, 'SIGTERM');
@@ -154,9 +202,16 @@ export default async function allVerdictsExecutor(
154
202
  };
155
203
  process.on('exit', onExit);
156
204
  for (const [signal, listener] of listeners) process.on(signal, listener);
205
+ // A command that needs no run is already judged: its block prints now, the others' as they close.
206
+ for (const run of runs) if (run.verdict !== null) process.stdout.write(block(run));
157
207
 
158
208
  const verdicts = await Promise.all(
159
- runs.map(async (run): Promise<CommandVerdict> => ({ command: run.command, verdict: await judge(run, cwd) })),
209
+ runs.map(
210
+ async (run): Promise<CommandVerdict> => ({
211
+ command: run.command,
212
+ verdict: run.verdict ?? (await judge(run, cwd)),
213
+ }),
214
+ ),
160
215
  );
161
216
  detach();
162
217
  process.stdout.write(verdictReport(verdicts));
@@ -16,6 +16,10 @@
16
16
  "cwd": {
17
17
  "type": "string",
18
18
  "description": "Where every command runs, relative to the workspace root."
19
+ },
20
+ "eslintProjectRoot": {
21
+ "type": "string",
22
+ "description": "The project, by workspace-relative root, whose ESLint sources replace {eslintSources} in a command when it runs."
19
23
  }
20
24
  },
21
25
  "additionalProperties": false
@@ -1,10 +1,24 @@
1
1
  /** The executor the inferred `lint` target runs its tool commands with. */
2
2
  export const ALL_VERDICTS_EXECUTOR = '@smoothbricks/nx-plugin:all-verdicts';
3
3
 
4
+ /**
5
+ * Where an inferred ESLint command names its files. The graph holds no list of them: a list is the files of the moment
6
+ * the graph was computed, and a run that outlives that moment fails on a file since deleted (ESLint refuses a pattern
7
+ * no file matches) and skips one since added. The executor replaces each occurrence with the files ESLint is handed
8
+ * when the command runs.
9
+ */
10
+ export const ESLINT_SOURCES_TOKEN = '{eslintSources}';
11
+
4
12
  /** Options of `@smoothbricks/nx-plugin:all-verdicts`. */
5
13
  export interface AllVerdictsOptions {
6
14
  /** Shell commands, all started at once; none ends another. An empty list is refused: it could never fail. */
7
15
  readonly commands: readonly string[];
8
16
  /** Where every command runs, relative to the workspace root. */
9
17
  readonly cwd: string;
18
+ /**
19
+ * The project, by workspace-relative root, whose ESLint sources replace {@link ESLINT_SOURCES_TOKEN} in a command when
20
+ * it runs: its `src` files and those its `tsconfig.test.json` declares, read from a fresh workspace file index. A
21
+ * command that names the token with no project is refused. A project with none passes without running ESLint.
22
+ */
23
+ readonly eslintProjectRoot?: string;
10
24
  }
@@ -3,11 +3,10 @@
3
3
  * a pure function of the run's events and the times they happened at, so a table can test it with no clock and no
4
4
  * process (verdict.ts says why the bounds are separate).
5
5
  *
6
- * - The total ceiling runs from the spawn.
7
- * - The fixture ceiling runs from the spawn while a supervised fixture runs, and ends with the fixture's segment.
8
- * - The progress bound runs only while the runner is testing (runner-lifecycle.ts): from the spawn when the runner is
9
- * testing then (startup is bounded until a build declares itself), restarted by a finished test or by the clock
10
- * starting again after a build, and stopped while nothing tests.
6
+ * - A scheduled leaf arms nothing until its first grant. Later zero-hold intervals pause only the idle budget.
7
+ * - Any explicitly queued task process pauses idle, including alongside held grants; ceilings keep running.
8
+ * - The fixture ceiling ends with its segment. The idle clock also stops outside the testing lifecycle.
9
+ * - Finished tests reset the idle budget whether their release byte arrived before or after their output.
11
10
  */
12
11
 
13
12
  /** The limits a run was given, in milliseconds; an absent one never expires. */
@@ -17,18 +16,39 @@ export interface BoundLimits {
17
16
  readonly totalMs?: number;
18
17
  }
19
18
 
20
- /** When each armed bound expires, in the clock's milliseconds; `null` when it is not armed. */
19
+ /**
20
+ * When each armed bound expires, in the clock's milliseconds; `null` when it is not armed. `queued`: the run waits for
21
+ * its pool's grant, so none is armed yet.
22
+ */
21
23
  export interface Bounds {
22
24
  readonly idle: number | null;
23
25
  readonly fixture: number | null;
24
26
  readonly total: number | null;
27
+ readonly queued: boolean;
28
+ readonly holds: number | null;
29
+ readonly idleRemaining: number | null;
30
+ readonly admissionWaiting: boolean;
25
31
  }
26
32
 
27
- export type BoundKind = keyof Bounds;
33
+ export type BoundKind = 'idle' | 'fixture' | 'total';
28
34
 
29
35
  export type BoundEvent =
30
- /** The command started; `testing` is the lifecycle's answer then, `fixture` whether a supervised fixture leads it. */
31
- | { readonly kind: 'spawn'; readonly at: number; readonly testing: boolean; readonly fixture: boolean }
36
+ /**
37
+ * The command started; `testing` is the lifecycle's answer then, `fixture` whether a supervised fixture leads it,
38
+ * `queued` whether mbx schedules this leaf, as known before spawn.
39
+ */
40
+ | {
41
+ readonly kind: 'spawn';
42
+ readonly at: number;
43
+ readonly testing: boolean;
44
+ readonly fixture: boolean;
45
+ readonly queued: boolean;
46
+ }
47
+ /** Each admission begins a hold; the first one starts the queued leaf's ceilings. */
48
+ | { readonly kind: 'granted'; readonly at: number; readonly testing: boolean; readonly fixture: boolean }
49
+ | { readonly kind: 'released'; readonly at: number }
50
+ /** A successful public snapshot proved whether a live task process is queued; `at` is completion, not poll start. */
51
+ | { readonly kind: 'admission-queue'; readonly at: number; readonly waiting: boolean; readonly testing: boolean }
32
52
  /**
33
53
  * The runner's state may have moved: a test finished (`finished`), a phase changed, or the lifecycle failed.
34
54
  * `wasTesting` is the answer before the event, `testing` the answer after it.
@@ -43,22 +63,95 @@ export type BoundEvent =
43
63
  /** The fixture's segment ended: its ceiling no longer applies. */
44
64
  | { readonly kind: 'fixture-done' };
45
65
 
46
- export const UNARMED: Bounds = { idle: null, fixture: null, total: null };
66
+ export const UNARMED: Bounds = {
67
+ idle: null,
68
+ fixture: null,
69
+ total: null,
70
+ queued: false,
71
+ admissionWaiting: false,
72
+ holds: null,
73
+ idleRemaining: null,
74
+ };
75
+
76
+ /** The bounds a command that starts running at `at` arms. */
77
+ function armed(limits: BoundLimits, at: number, testing: boolean, fixture: boolean): Bounds {
78
+ return {
79
+ idle: testing && limits.idleMs !== undefined ? at + limits.idleMs : null,
80
+ fixture: fixture && limits.fixtureMs !== undefined ? at + limits.fixtureMs : null,
81
+ total: limits.totalMs !== undefined ? at + limits.totalMs : null,
82
+ queued: false,
83
+ admissionWaiting: false,
84
+ holds: null,
85
+ idleRemaining: limits.idleMs ?? null,
86
+ };
87
+ }
47
88
 
48
89
  /** The bounds after `event`. */
49
90
  export function stepBounds(bounds: Bounds, limits: BoundLimits, event: BoundEvent): Bounds {
50
91
  switch (event.kind) {
51
92
  case 'spawn':
93
+ return event.queued
94
+ ? { ...UNARMED, queued: true, holds: 0, idleRemaining: limits.idleMs ?? null }
95
+ : armed(limits, event.at, event.testing, event.fixture);
96
+ case 'granted': {
97
+ if (bounds.holds === null) return bounds;
98
+ if (bounds.queued) {
99
+ const admitted = armed(limits, event.at, event.testing, event.fixture);
100
+ return {
101
+ ...admitted,
102
+ holds: 1,
103
+ admissionWaiting: bounds.admissionWaiting,
104
+ idle: bounds.admissionWaiting ? null : admitted.idle,
105
+ };
106
+ }
107
+ return {
108
+ ...bounds,
109
+ holds: bounds.holds + 1,
110
+ idle:
111
+ bounds.holds === 0 && !bounds.admissionWaiting && event.testing && bounds.idleRemaining !== null
112
+ ? event.at + bounds.idleRemaining
113
+ : bounds.idle,
114
+ };
115
+ }
116
+ case 'admission-queue': {
117
+ if (bounds.admissionWaiting === event.waiting) return bounds;
118
+ if (event.waiting) {
119
+ return {
120
+ ...bounds,
121
+ admissionWaiting: true,
122
+ idle: null,
123
+ idleRemaining: bounds.idle === null ? bounds.idleRemaining : Math.max(0, bounds.idle - event.at),
124
+ };
125
+ }
52
126
  return {
53
- idle: event.testing && limits.idleMs !== undefined ? event.at + limits.idleMs : null,
54
- fixture: event.fixture && limits.fixtureMs !== undefined ? event.at + limits.fixtureMs : null,
55
- total: limits.totalMs !== undefined ? event.at + limits.totalMs : null,
127
+ ...bounds,
128
+ admissionWaiting: false,
129
+ idle:
130
+ !bounds.queued && bounds.holds !== 0 && event.testing && bounds.idleRemaining !== null
131
+ ? event.at + bounds.idleRemaining
132
+ : null,
56
133
  };
134
+ }
135
+ case 'released': {
136
+ if (bounds.holds === null || bounds.holds === 0) return bounds;
137
+ if (bounds.holds > 1) return { ...bounds, holds: bounds.holds - 1 };
138
+ return {
139
+ ...bounds,
140
+ holds: 0,
141
+ idle: null,
142
+ idleRemaining: bounds.idle === null ? bounds.idleRemaining : Math.max(0, bounds.idle - event.at),
143
+ };
144
+ }
57
145
  case 'progress': {
58
- if (!event.testing) return { ...bounds, idle: null };
146
+ if (bounds.queued) return event.finished ? { ...bounds, idleRemaining: limits.idleMs ?? null } : bounds;
147
+ if (!event.testing) return { ...bounds, idle: null, idleRemaining: limits.idleMs ?? null };
59
148
  const restart = event.finished || !event.wasTesting;
60
149
  if (!restart || limits.idleMs === undefined) return bounds;
61
- return { ...bounds, idle: event.at + limits.idleMs };
150
+ return {
151
+ ...bounds,
152
+ idle: bounds.holds === 0 || bounds.admissionWaiting ? null : event.at + limits.idleMs,
153
+ idleRemaining: limits.idleMs,
154
+ };
62
155
  }
63
156
  case 'fixture-done':
64
157
  return { ...bounds, fixture: null };
@@ -74,3 +167,27 @@ export function earliestBound(bounds: Bounds): { readonly kind: BoundKind; reado
74
167
  }
75
168
  return earliest;
76
169
  }
170
+
171
+ /** Observed queue duration on a monotonic clock; stopping closes its interval permanently, before cleanup begins. */
172
+ export type AdmissionWait =
173
+ | { readonly kind: 'observing'; readonly since: number | null; readonly waitedMs: number }
174
+ | { readonly kind: 'stopped'; readonly waitedMs: number };
175
+
176
+ export type AdmissionWaitEvent =
177
+ | { readonly kind: 'snapshot'; readonly at: number; readonly waiting: boolean }
178
+ | { readonly kind: 'stop'; readonly at: number };
179
+
180
+ export const NO_ADMISSION_WAIT: AdmissionWait = { kind: 'observing', since: null, waitedMs: 0 };
181
+
182
+ /** Read the observed duration, not the time later spent tearing down the command or reading its report. */
183
+ export function admissionWaitMs(wait: AdmissionWait, at: number): number {
184
+ return wait.waitedMs + (wait.kind === 'observing' && wait.since !== null ? at - wait.since : 0);
185
+ }
186
+
187
+ /** A successful completed observation opens/closes an interval; terminal/cancellation stops freeze it. */
188
+ export function stepAdmissionWait(wait: AdmissionWait, event: AdmissionWaitEvent): AdmissionWait {
189
+ if (wait.kind === 'stopped') return wait;
190
+ if (event.kind === 'stop') return { kind: 'stopped', waitedMs: admissionWaitMs(wait, event.at) };
191
+ if (event.waiting) return wait.since === null ? { ...wait, since: event.at } : wait;
192
+ return wait.since === null ? wait : { kind: 'observing', since: null, waitedMs: admissionWaitMs(wait, event.at) };
193
+ }