nx 23.3.0-beta.7 → 23.3.0-beta.9

package/dist/src/command-line/migrate/run/state-machine.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyStepEvent = applyStepEvent;
 exports.discardGeneratorRun = discardGeneratorRun;
+exports.tallySteps = tallySteps;
+exports.runTallies = runTallies;
+exports.unresolvedFailureDetail = unresolvedFailureDetail;
+exports.completionSummaryLines = completionSummaryLines;
+exports.unresolvedCommitName = unresolvedCommitName;
 exports.markInstallFailed = markInstallFailed;
 exports.uncoveredFailedStepIds = uncoveredFailedStepIds;
 exports.hasPendingCommitDebt = hasPendingCommitDebt;
@@ -14,7 +19,9 @@ exports.commitReceipt = commitReceipt;
 exports.latestRound = latestRound;
 exports.splitMigrationId = splitMigrationId;
 exports.stepsToPendingMigrations = stepsToPendingMigrations;
+exports.gitRan = gitRan;
 exports.commitResultToLedgerEntry = commitResultToLedgerEntry;
+const text_1 = require("../text");
 const PROMPT_OUTCOME_TO_STEP_STATUS = {
     completed: 'succeeded',
     skipped: 'skipped',
@@ -130,14 +137,20 @@ function applyStepAction(state, index, step, action) {
                 // exec side effect, or a crash mid-flush), so a reset-backed retry is
                 // offered under the same guard as for a death.
                 return commit(state, index, cleanRearm(state, step));
+            case 'adopt':
+                return commit(state, index, adopt(step));
             case 'skip':
+            case 'unresolved':
                 if (commitMayBeInHistory(state, step)) {
                     return {
                         kind: 'error',
-                        reason: `Cannot apply action 'skip' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the migration may be committed. Use 'retry' to finish it.`,
+                        reason: `Cannot apply action '${action}' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the migration may be committed. Use 'adopt' to record it as applied once the migration is finished.`,
                     };
                 }
-                return commit(state, index, { ...step, status: 'skipped' });
+                return commit(state, index, {
+                    ...step,
+                    status: action === 'skip' ? 'skipped' : 'unresolved',
+                });
         }
     }
     if (step.status === 'died') {
@@ -155,16 +168,12 @@ function applyStepAction(state, index, step, action) {
                     kind: 'error',
                     reason: `Cannot apply action 'retry' to step '${step.id}': the worker died before recording that its generator ran, so keeping the current tree could apply the migration twice. Use ${commitMayBeInHistory(state, step)
                         ? `'retry-clean' where offered, or 'adopt'`
-                        : `'retry-clean', 'adopt' or 'skip'`} instead.`,
+                        : `'retry-clean', 'adopt', 'skip' or 'unresolved'`} instead.`,
                 };
             case 'retry-clean':
                 return commit(state, index, cleanRearm(state, step));
             case 'adopt':
-                return commit(state, index, {
-                    ...step,
-                    status: 'succeeded',
-                    outcome: { ...step.outcome, summary: adoptedSummary(step) },
-                });
+                return commit(state, index, adopt(step));
             case 'skip': {
                 if (coveringLandedEntries(state, step.id).length > 0) {
                     return {
@@ -181,6 +190,20 @@ function applyStepAction(state, index, step, action) {
                 // Same as skipping a failure: the tree stays as the worker left it.
                 return commit(state, index, { ...step, status: 'skipped' });
             }
+            case 'unresolved':
+                if (commitMayBeInHistory(state, step)) {
+                    return {
+                        kind: 'error',
+                        reason: `Cannot apply action 'unresolved' to step '${step.id}': a commit of its changes landed or was started and never recorded, so the migration may be committed. Use 'adopt' to record it as applied once the migration is finished.`,
+                    };
+                }
+                // A death records no outcome, so the failure given up on is the death
+                // itself.
+                return commit(state, index, {
+                    ...step,
+                    status: 'unresolved',
+                    outcome: { summary: workerDiedSummary(step) },
+                });
         }
     }
     return {
@@ -188,6 +211,9 @@ function applyStepAction(state, index, step, action) {
         reason: `Cannot apply action '${action}' to step '${step.id}' in status '${step.status}'.`,
     };
 }
+function workerDiedSummary(step) {
+    return `the worker process${step.pid === undefined ? '' : ` (pid ${step.pid})`} died before recording an outcome`;
+}
 // Re-arms for a retry that resets the tree first. The reset target predates
 // the generator unless a commit of this step's own already carries it, so the
 // marker only survives when such a commit exists; otherwise the reset discards
@@ -195,9 +221,18 @@ function applyStepAction(state, index, step, action) {
 function cleanRearm(state, step) {
     return rearm(step, coveringLandedEntries(state, step.id).length > 0);
 }
-// An adopted death records how far the worker got, since 'succeeded' alone
-// says the migration was applied and cannot say by what.
+function adopt(step) {
+    return {
+        ...step,
+        status: 'succeeded',
+        adopted: true,
+        outcome: { ...step.outcome, summary: adoptedSummary(step) },
+    };
+}
 function adoptedSummary(step) {
+    if (step.status === 'failed') {
+        return "Adopted after the attempt failed: the working tree as it stood was taken as this migration's result.";
+    }
     return step.generatorCompleted === true
         ? "Adopted after the worker died: its generator had run, and the working tree it left was taken as this migration's result."
         : "Adopted after the worker died before recording that its generator had run; the working tree it left was taken as this migration's result.";
@@ -264,6 +299,80 @@ function discardGeneratorRun(state, stepId) {
         }),
     };
 }
+function tallySteps(state) {
+    const tally = {
+        applied: 0,
+        adopted: 0,
+        skipped: 0,
+        unresolved: [],
+        remaining: 0,
+        stalled: 0,
+    };
+    for (const step of state.steps) {
+        switch (step.status) {
+            case 'succeeded':
+                if (step.adopted)
+                    tally.adopted++;
+                else
+                    tally.applied++;
+                break;
+            case 'skipped':
+                tally.skipped++;
+                break;
+            case 'unresolved':
+                tally.unresolved.push(step);
+                break;
+            case 'failed':
+            case 'died':
+                tally.stalled++;
+                tally.remaining++;
+                break;
+            case 'pending':
+            case 'dispensed':
+            case 'running':
+            case 'awaiting-prompt-outcome':
+                tally.remaining++;
+                break;
+            default: {
+                const exhaustive = step.status;
+                throw new Error(`Unhandled step status '${exhaustive}'.`);
+            }
+        }
+    }
+    return tally;
+}
+function runTallies(state) {
+    const tally = tallySteps(state);
+    return {
+        completed: tally.applied + tally.adopted,
+        skipped: tally.skipped,
+        unresolved: tally.unresolved.length,
+        dispenseCount: state.steps.reduce((n, s) => n + s.dispenseCount, 0),
+    };
+}
+// The failure a given-up step is reported with, in the issue ledger and the
+// completion report alike. Agent text is collapsed to one line so a break
+// inside it cannot open a block at a line start; an accepted handoff may carry
+// an empty summary, which gets the fallback.
+function unresolvedFailureDetail(step) {
+    const failure = (0, text_1.singleLine)(step.outcome?.summary ?? step.promptOutcome?.summary ?? '').trim();
+    return failure.length === 0 ? 'no failure detail was recorded' : failure;
+}
+function completionSummaryLines(state) {
+    const tally = tallySteps(state);
+    return [
+        `  applied: ${tally.applied}`,
+        `  adopted: ${tally.adopted}`,
+        `  skipped: ${tally.skipped}`,
+        `  unresolved: ${tally.unresolved.length}`,
+        ...tally.unresolved.map((step) => `    - ${step.migrationId}: ${unresolvedFailureDetail(step)}`),
+    ];
+}
+// Suffixed so history does not read the partial result as the migration
+// applied.
+function unresolvedCommitName(step) {
+    return `${splitMigrationId(step.migrationId).name} (unresolved)`;
+}
 // A guarded transition whose observation was made against an earlier attempt
 // of the same step: the status recurred, so the observation says nothing about
 // the attempt on disk now.
@@ -405,6 +514,24 @@ function stepsToPendingMigrations(state, stepIds) {
     }
     return pending;
 }
+// Whether git may have written history for this result. A landed commit's
+// mark is the ledger entry's to clear, and a failure reported once git ran
+// (a hook's output overflowing the subprocess buffer after the commit) cannot
+// vouch that nothing landed, so only the other results release the mark.
+function gitRan(result) {
+    switch (result.status) {
+        case 'committed':
+        case 'failed':
+            return true;
+        case 'no-changes':
+        case 'disabled':
+            return false;
+        default: {
+            const exhaustive = result;
+            throw new Error(`Unhandled commit result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
 /**
  * Classifies a commit attempt into the ledger entry to record, or null when
  * there is nothing to record ('no-changes' / 'disabled'). A landed entry

package/dist/src/command-line/migrate/run/util.d.ts

@@ -57,4 +57,5 @@ export declare function isPidAlive(pid: number): boolean;
 export declare function summarizeError(e: unknown): string;
 export declare function warnCommitFailed(name: string, cause?: unknown): void;
 export declare function pmExecPrefix(root: string): string;
+export declare function runMigrationsFlag(migrationsPath: string): string | null;
 export declare function pmInstallCommand(root: string): string;

package/dist/src/command-line/migrate/run/util.js

@@ -9,12 +9,15 @@ exports.isPidAlive = isPidAlive;
 exports.summarizeError = summarizeError;
 exports.warnCommitFailed = warnCommitFailed;
 exports.pmExecPrefix = pmExecPrefix;
+exports.runMigrationsFlag = runMigrationsFlag;
 exports.pmInstallCommand = pmInstallCommand;
 const crypto_1 = require("crypto");
+const shell_quoting_1 = require("../../../utils/shell-quoting");
 const package_manager_1 = require("../../../utils/package-manager");
 const execute_migration_1 = require("../execute-migration");
 const state_lock_1 = require("./state-lock");
 const agent_output_1 = require("./agent-output");
+const text_1 = require("../text");
 function nowIso() {
     return new Date().toISOString();
 }
@@ -143,6 +146,24 @@ function pmCommands(root) {
 function pmExecPrefix(root) {
     return pmCommands(root).exec;
 }
+const DEFAULT_MIGRATIONS_FILE = 'migrations.json';
+// The --run-migrations flag a rendered command repeats; null when the path
+// cannot go out as a one-line command for this shell. On Windows the paste
+// target may be cmd.exe or PowerShell, whose quoting and expansion conflict
+// (`%VAR%` expands in cmd, `$(...)` runs in PowerShell).
+function runMigrationsFlag(migrationsPath) {
+    if (migrationsPath === DEFAULT_MIGRATIONS_FILE) {
+        return '--run-migrations';
+    }
+    if ((0, text_1.hasLineBreak)(migrationsPath)) {
+        return null;
+    }
+    const arg = `--run-migrations=${migrationsPath}`;
+    if (process.platform !== 'win32') {
+        return (0, shell_quoting_1.quoteShellArg)(arg);
+    }
+    return !(0, shell_quoting_1.needsShellQuoting)(arg) && !/[%^]/.test(arg) ? arg : null;
+}
 function pmInstallCommand(root) {
     return pmCommands(root).install;
 }

package/dist/src/command-line/migrate/run/worker.js

@@ -105,6 +105,9 @@ function readMigrationsSource(root, runId) {
         if (!(0, run_state_1.hasRunState)(dir)) {
             throw new Error(`No migrate run '${runId}' was found under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}.`);
         }
+        // Before the state and plan reads: a concurrent start-fresh must not
+        // delete the run while this worker resolves its migration.
+        (0, state_lock_1.holdRunActivity)(root, runId);
         // Version refusal (NewerRunStateFormatError) propagates.
         const state = (0, run_state_1.readRunState)(dir);
         const round = (0, state_machine_1.latestRound)(state);

package/dist/src/command-line/migrate/step-actions.d.ts

@@ -1,5 +1,5 @@
 /** Allowed values for `--step-action`, the orchestrated reconcile's decision relay. */
-export declare const STEP_ACTIONS: readonly ['retry', 'skip', 'retry-clean', 'adopt'];
+export declare const STEP_ACTIONS: readonly ['retry', 'skip', 'retry-clean', 'adopt', 'unresolved'];
 export type StepAction = (typeof STEP_ACTIONS)[number];
 /** Runtime guard backed by {@link STEP_ACTIONS} so the two can't drift apart. */
 export declare function isStepAction(value: unknown): value is StepAction;

package/dist/src/command-line/migrate/step-actions.js

@@ -5,7 +5,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.STEP_ACTIONS = void 0;
 exports.isStepAction = isStepAction;
 /** Allowed values for `--step-action`, the orchestrated reconcile's decision relay. */
-exports.STEP_ACTIONS = ['retry', 'skip', 'retry-clean', 'adopt'];
+exports.STEP_ACTIONS = [
+    'retry',
+    'skip',
+    'retry-clean',
+    'adopt',
+    'unresolved',
+];
 /** Runtime guard backed by {@link STEP_ACTIONS} so the two can't drift apart. */
 function isStepAction(value) {
     return exports.STEP_ACTIONS.includes(value);

package/dist/src/command-line/migrate/text.d.ts

@@ -16,3 +16,9 @@
  * real terminator can put a value at the start of a line.
  */
 export declare function singleLine(value: string): string;
+export declare function hasLineBreak(value: string): boolean;
+/**
+ * Renders an ISO timestamp as a human age ("6 hours ago"), falling back to
+ * the raw value when it is not parseable or lies in the future.
+ */
+export declare function formatAge(timestamp: string): string;

package/dist/src/command-line/migrate/text.js

@@ -4,6 +4,8 @@
 // run/util.ts without a cycle through run/state-lock.ts.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.singleLine = singleLine;
+exports.hasLineBreak = hasLineBreak;
+exports.formatAge = formatAge;
 /**
  * Collapses every character a reader could take for a line break, so a value
  * cannot break out of the line it is rendered on. The driving agent scans the
@@ -24,3 +26,26 @@ exports.singleLine = singleLine;
 function singleLine(value) {
     return value.replace(/[\r\n\u000b\u000c\u0085\u2028\u2029]+/g, ' ');
 }
+function hasLineBreak(value) {
+    return singleLine(value) !== value;
+}
+/**
+ * Renders an ISO timestamp as a human age ("6 hours ago"), falling back to
+ * the raw value when it is not parseable or lies in the future.
+ */
+function formatAge(timestamp) {
+    const elapsedMs = Date.now() - Date.parse(timestamp);
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 0) {
+        return timestamp;
+    }
+    const minutes = Math.floor(elapsedMs / 60_000);
+    if (minutes < 60) {
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    }
+    const hours = Math.floor(elapsedMs / 3_600_000);
+    if (hours < 48) {
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    }
+    const days = Math.floor(elapsedMs / 86_400_000);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}

package/dist/src/command-line/release/utils/release-graph.js

@@ -437,7 +437,7 @@ class ReleaseGraph {
         if (!releaseGroup ||
             !this.projectsToVersionActions.has(projectName) ||
             !this.finalConfigsByProject.has(projectName)) {
-            throw new Error(`Cannot resolve a concrete current version for dependency project "${projectName}" because it is not configured for Nx Release. Include the project in an Nx Release group so that its current version resolver can be configured.`);
+            throw Object.assign(new Error(`Cannot resolve a concrete current version for dependency project "${projectName}" because it is not configured for Nx Release. Include the project in an Nx Release group so that its current version resolver can be configured.`), { code: 'NX_RELEASE_PROJECT_NOT_CONFIGURED' });
         }
         let currentVersion;
         try {

package/dist/src/command-line/release/utils/remote-release-clients/github.js

@@ -11,8 +11,7 @@ const output_1 = require("../../../../utils/output");
 const path_1 = require("../../../../utils/path");
 const extract_repo_slug_1 = require("./extract-repo-slug");
 const remote_release_client_1 = require("./remote-release-client");
-// Use default import with esModuleInterop
-const axios_1 = tslib_1.__importDefault(require("axios"));
+const http_client_1 = require("../../../../utils/http-client");
 exports.defaultCreateReleaseProvider = {
     provider: 'github',
     hostname: 'github.com',
@@ -117,9 +116,7 @@ class GithubRemoteReleaseClient extends remote_release_client_1.RemoteReleaseCli
                         break;
                     }
                 }
-                const { data } = await axios_1.default
-                    .get(`https://ungh.cc/users/find/${email}`)
-                    .catch(() => ({ data: { user: null } }));
+                const { data } = await (0, http_client_1.httpRequest)(`https://ungh.cc/users/find/${email}`).catch(() => ({ data: { user: null } }));
                 if (data?.user?.username) {
                     meta.username = data.user.username;
                     break;

package/dist/src/command-line/release/utils/remote-release-clients/remote-release-client.d.ts

@@ -1,7 +1,7 @@
-import type { AxiosRequestConfig } from 'axios';
 import type { PostGitTask } from '../../changelog';
 import { ResolvedCreateRemoteReleaseProvider } from '../../config/config';
 import type { Reference } from '../git';
+import { type HttpRequestConfig } from '../../../../utils/http-client';
 import { type ReleaseVersion } from '../shared';
 import type { GithubRemoteReleaseClient } from './github';
 import type { GitLabRemoteReleaseClient } from './gitlab';
@@ -62,7 +62,7 @@ export declare abstract class RemoteReleaseClient<RemoteRelease extends Record<s
     /**
      * Make an (optionally authenticated) API request to the remote release provider
      */
-    protected makeRequest(url: string, opts?: AxiosRequestConfig): Promise<any>;
+    protected makeRequest(url: string, opts?: HttpRequestConfig): Promise<any>;
     createOrUpdateRelease(releaseVersion: ReleaseVersion, changelogContents: string, latestCommit: string, { dryRun }: {
         dryRun: boolean;
     }): Promise<void>;

package/dist/src/command-line/release/utils/remote-release-clients/remote-release-client.js

@@ -2,10 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RemoteReleaseClient = void 0;
 exports.createRemoteReleaseClient = createRemoteReleaseClient;
-const tslib_1 = require("tslib");
 const node_util_1 = require("node:util");
-const axios_1 = tslib_1.__importDefault(require("axios"));
 const handle_import_1 = require("../../../../utils/handle-import");
+const http_client_1 = require("../../../../utils/http-client");
 const print_changes_1 = require("../print-changes");
 const shared_1 = require("../shared");
 /**
@@ -33,10 +32,10 @@ class RemoteReleaseClient {
     }
     inspectWithRedactedToken(error) {
         const inspected = (0, node_util_1.inspect)(error);
-        // The dump can hold a different string than the raw token: axios trims
+        // The dump can hold a different string than the raw token: fetch trims
         // header values and inspect() escapes the result, while message/stack keep
         // it bare. Redact every rendering; the Set collapses them for an ordinary
-        // token. The CR/LF needle is belt-and-braces — node rejects such headers.
+        // token. The CR/LF needle is belt-and-braces - fetch rejects such headers.
         const token = this.tokenData?.token?.trim();
         if (!token) {
             return inspected;
@@ -81,7 +80,7 @@ class RemoteReleaseClient {
                 ...this.tokenHeader,
             },
         };
-        return (await (0, axios_1.default)(url, config)).data;
+        return (await (0, http_client_1.httpRequest)(url, config)).data;
     }
     async createOrUpdateRelease(releaseVersion, changelogContents, latestCommit, { dryRun }) {
         let existingRelease;

package/dist/src/command-line/release/version/version-actions.d.ts

@@ -15,6 +15,9 @@ export type SemverBumpType = ReleaseType | 'none';
  * when it is part of the release, or its current version when it is not being
  * versioned.
  *
+ * When the project is not configured for Nx Release, the returned promise
+ * rejects with an error whose `code` is `NX_RELEASE_PROJECT_NOT_CONFIGURED`.
+ *
  * @public
  */
 export type ResolveVersionForDependency = (dependencyProjectName: string) => Promise<string>;

package/dist/src/command-line/reset/reset.js

@@ -12,6 +12,7 @@ const client_2 = require("../../nx-cloud/utilities/client");
 const get_cloud_options_1 = require("../../nx-cloud/utilities/get-cloud-options");
 const nx_cloud_utils_1 = require("../../utils/nx-cloud-utils");
 const configuration_1 = require("../../config/configuration");
+const db_connection_1 = require("../../utils/db-connection");
 const update_manager_1 = require("../../nx-cloud/update-manager");
 // Wait at max 5 seconds before giving up on a failing operation.
 const INCREMENTAL_BACKOFF_MAX_DURATION = 5000;
@@ -82,6 +83,11 @@ async function resetHandler(args) {
     if ((cloudEnabled && all) || args.onlyCloud) {
         try {
             await resetCloudClient();
+        }
+        catch (e) {
+            errors.push('Failed to clean up the Nx Cloud client.', e.toString());
+        }
+        try {
             await removeInstalledNxCloudClient();
         }
         catch (e) {
@@ -117,10 +123,8 @@ function cleanupDaemonWorkspaceData() {
 async function resetCloudClient() {
     // Remove nx cloud marker files. This helps if the use happens to run `nx-cloud start-ci-run` or
     // similar commands on their local machine.
-    try {
-        (await (0, client_2.getCloudClient)((0, get_cloud_options_1.getCloudOptions)())).invoke('cleanup');
-    }
-    catch { }
+    // `exit` would end the process here, before reset reports its result.
+    await (await (0, client_2.getCloudClient)((0, get_cloud_options_1.getCloudOptions)())).invoke('cleanup', false);
 }
 function removeInstalledNxCloudClient() {
     return incrementalBackoff(INCREMENTAL_BACKOFF_FIRST_DELAY, INCREMENTAL_BACKOFF_MAX_DURATION, () => {
@@ -155,6 +159,8 @@ function cleanupNativeFileCache() {
 }
 function cleanupWorkspaceData() {
     return incrementalBackoff(INCREMENTAL_BACKOFF_FIRST_DELAY, INCREMENTAL_BACKOFF_MAX_DURATION, () => {
+        // Analytics opened the DB at startup; Windows cannot delete an open file.
+        (0, db_connection_1.removeDbConnections)();
         (0, node_fs_1.rmSync)(cache_directory_1.workspaceDataDirectory, { recursive: true, force: true });
         // Also clean wherever the DB actually lives, which is outside this
         // checkout whenever the shared root is reachable. Resolved through the

package/dist/src/command-line/show/command-object.js

@@ -37,7 +37,7 @@ exports.yargsShowCommand = {
 const showProjectsCommand = {
     command: 'projects',
     describe: 'Show a list of projects in the workspace.',
-    builder: (yargs) => (0, shared_options_1.withVerbose)((0, shared_options_1.withAffectedOptions)(yargs))
+    builder: (yargs) => (0, shared_options_1.withVerbose)((0, shared_options_1.withExplainOption)((0, shared_options_1.withAffectedOptions)(yargs)))
         .option('affected', {
         type: 'boolean',
         description: 'Show only affected projects.',

package/dist/src/command-line/show/projects.js

@@ -5,6 +5,8 @@ const output_1 = require("../../utils/output");
 const nx_json_1 = require("../../config/nx-json");
 const affected_project_graph_1 = require("../../project-graph/affected/affected-project-graph");
 const affected_tasks_1 = require("../../project-graph/affected/affected-tasks");
+const print_explanation_1 = require("../../project-graph/affected/print-explanation");
+const affected_reasons_1 = require("../../project-graph/affected/affected-reasons");
 const file_utils_1 = require("../../project-graph/file-utils");
 const operators_1 = require("../../project-graph/operators");
 const project_graph_1 = require("../../project-graph/project-graph");
@@ -18,6 +20,17 @@ async function showProjectsHandler(args) {
     const { nxArgs } = (0, command_line_utils_1.splitArgsIntoNxArgsAndOverrides)(args, 'affected', {
         printWarnings: false,
     }, nxJson);
+    const explainsTasks = args.affected &&
+        (0, affected_tasks_1.selectsAffectedTasks)() &&
+        !!args.withTarget?.length &&
+        !args.projects;
+    if ((0, affected_reasons_1.isExplaining)(nxArgs.explain) && !explainsTasks) {
+        throw new Error((0, affected_reasons_1.explainUnavailable)([
+            !(0, affected_tasks_1.selectsAffectedTasks)() && 'NX_LEGACY_AFFECTED=false',
+            !args.affected && '--affected',
+            !args.withTarget?.length && 'targets passed with --withTarget (-t)',
+        ].filter(Boolean), args.projects ? ['--projects'] : []));
+    }
     // Affected touches dependencies so it needs to be processed first.
     if (args.affected) {
         const touchedFiles = await getTouchedFiles(nxArgs);
@@ -33,8 +46,17 @@ async function showProjectsHandler(args) {
                     head: nxArgs.head,
                     files: nxArgs.files,
                 },
+                explain: (0, affected_reasons_1.isExplaining)(nxArgs.explain),
                 ...(await runCommandModule().runnerInputsForSelection(nxArgs, nxJson)),
             });
+            if ((0, affected_reasons_1.isExplaining)(nxArgs.explain)) {
+                (0, print_explanation_1.printAffectedExplanation)(affectedTasks.explanation, 'Affected tasks', 
+                // show projects declares its own --json, which has no executor to
+                // pass through to.
+                args.json ? 'stdout' : nxArgs.explain, { verbose: args.verbose });
+                await output_1.output.drain();
+                return;
+            }
             const { taskGraph, initiatingTaskIds } = affectedTasks.taskSelection;
             const owning = new Set(initiatingTaskIds.map((id) => taskGraph.tasks[id].target.project));
             // The graph selection ran against: with the daemon on, the daemon's, not `graph`.

package/dist/src/command-line/yargs-utils/shared-options.d.ts

@@ -54,6 +54,10 @@ export declare function withAffectedOptions(yargs: Argv): Argv<ExcludeOptions &
 } & {
     head: string;
 }>;
+/** Only on the commands that report instead of running when it is passed. */
+export declare function withExplainOption<T>(yargs: Argv<T>): Argv<T & {
+    explain?: string | boolean;
+}>;
 export interface RunManyOptions extends RunOptions {
     projects: string[];
     /**

package/dist/src/command-line/yargs-utils/shared-options.js

@@ -9,6 +9,7 @@ exports.withConfiguration = withConfiguration;
 exports.withVerbose = withVerbose;
 exports.withBatch = withBatch;
 exports.withAffectedOptions = withAffectedOptions;
+exports.withExplainOption = withExplainOption;
 exports.withRunManyOptions = withRunManyOptions;
 exports.withOverrides = withOverrides;
 exports.withOutputStyleOption = withOutputStyleOption;
@@ -244,6 +245,21 @@ function withAffectedOptions(yargs) {
         }
     }, true);
 }
+/** Only on the commands that report instead of running when it is passed. */
+function withExplainOption(yargs) {
+    return yargs.option('explain', {
+        type: 'string',
+        describe: 'Print why each task was considered affected, instead of running anything. Needs task selection (NX_LEGACY_AFFECTED=false). Pass a file path to save the reasons as JSON instead. Pass "stdout" to print the JSON to the terminal.',
+        // Same shape as `--graph`: the value is a destination, and a bare
+        // `--explain` has to arrive as a boolean. `nx affected` leaves `--json`
+        // undeclared so it still reaches the executor.
+        coerce: (value) => value === '' || value === 'true' || value === true
+            ? true
+            : value === 'false' || value === false
+                ? false
+                : value,
+    });
+}
 function withRunManyOptions(yargs) {
     return withRunOptions(yargs)
         .parserConfiguration(exports.defaultYargsParserConfiguration)

package/dist/src/config/task-graph.d.ts

@@ -3,4 +3,4 @@
  * `packages/nx/src/native/tasks/types.rs` and exposed to TypeScript via NAPI.
  * This file re-exports them so existing imports keep working.
  */
-export type { Task, TaskGraph, TaskTarget, TaskHashDetails, TaskUltracacheConfiguration, } from '../native';
+export type { Task, TaskGraph, TaskTarget, TaskHashDetails, TaskUltracacheSettings, } from '../native';

package/dist/src/config/workspace-json-project-json.d.ts

@@ -1,4 +1,4 @@
-import type { JsonInput, TaskUltracacheConfiguration } from '../native';
+import type { JsonInput, TaskUltracacheSettings } from '../native';
 import type { PackageJson } from '../utils/package-json';
 import type { NxJsonConfiguration, NxReleaseDockerConfiguration, NxReleaseVersionConfiguration } from './nx-json';
 /**
@@ -156,13 +156,13 @@ export type Spreadable<T> = T & {
     '...'?: true;
 };
 /**
- * Ultracache configuration for a target's tasks.
+ * Ultracache settings for a target's tasks.
  *
  * The resolved shape rides on each Task instance (`Task['ultracache']`), which
  * is why it is shared with the native task definition. Authoring additionally
  * permits `'...'`, which target merging resolves away.
  */
-export type TargetUltracacheConfiguration = Spreadable<TaskUltracacheConfiguration>;
+export type TargetUltracacheSettings = Spreadable<TaskUltracacheSettings>;
 export interface TargetDependencyConfig {
     /**
      * A list of projects that have `target`.
@@ -263,7 +263,7 @@ export interface TargetConfiguration<T = any> {
     /**
      * Configures ultracache for tasks of this target. Nx Cloud only.
      */
-    ultracache?: TargetUltracacheConfiguration;
+    ultracache?: TargetUltracacheSettings;
     /**
      * Metadata about the target
      */

package/dist/src/daemon/client/client.d.ts

@@ -1,7 +1,7 @@
 import { ChildProcess } from 'child_process';
 import { FileData, ProjectGraph } from '../../config/project-graph';
 import { Task, TaskGraph } from '../../config/task-graph';
-import type { IoSnapshotVersion } from '../message-types/io-snapshot-version';
+import type { UltracacheConfigurationVersion } from '../message-types/ultracache-configuration-version';
 import { Hash } from '../../hasher/task-hasher';
 import { NxWorkspaceFiles, TaskRun, TaskTarget } from '../../native';
 import { PreTasksExecutionContext } from '../../project-graph/plugins/public-api';
@@ -61,8 +61,8 @@ export declare class DaemonClient {
         sourceMaps: ConfigurationSourceMaps;
     }>;
     getAllFileData(): Promise<FileData[]>;
-    hashTasks(runnerOptions: any, tasks: Task[], taskGraph: TaskGraph, perTaskEnvs: Record<string, NodeJS.ProcessEnv>, cwd: string, collectInputs?: boolean, ioSnapshots?: IoSnapshotVersion): Promise<Hash[]>;
-    hashTasksUpfront(runnerOptions: any, tasks: Task[], taskGraph: TaskGraph, perTaskEnvs: Record<string, NodeJS.ProcessEnv>, cwd: string, collectInputs?: boolean, ioSnapshots?: IoSnapshotVersion): Promise<Record<string, Hash>>;
+    hashTasks(runnerOptions: any, tasks: Task[], taskGraph: TaskGraph, perTaskEnvs: Record<string, NodeJS.ProcessEnv>, cwd: string, collectInputs?: boolean, ultracacheConfigurationsVersion?: UltracacheConfigurationVersion): Promise<Hash[]>;
+    hashTasksUpfront(runnerOptions: any, tasks: Task[], taskGraph: TaskGraph, perTaskEnvs: Record<string, NodeJS.ProcessEnv>, cwd: string, collectInputs?: boolean, ultracacheConfigurationsVersion?: UltracacheConfigurationVersion): Promise<Record<string, Hash>>;
     registerFileWatcher(config: {
         watchProjects: string[] | 'all';
         includeGlobalWorkspaceFiles?: boolean;