nx 23.0.0-beta.21 → 23.0.0-beta.23

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyNxJsonMigrateDefaults = applyNxJsonMigrateDefaults;
+exports.assertCommitPrefixHasCommits = assertCommitPrefixHasCommits;
+const cli_args_1 = require("./agentic/cli-args");
+const command_object_1 = require("./command-object");
+const MULTI_MAJOR_MODE_ENV = 'NX_MULTI_MAJOR_MODE';
+/**
+ * Overlays `nx.json` `migrate` defaults onto the raw `nx migrate` CLI args so a
+ * CLI flag always wins, then `nx.json`, then the built-in default. Returns a new
+ * args object; the input is not mutated.
+ *
+ * Phase-aware: generate-only options (`mode`, `multiMajorMode`) are applied only
+ * when not running migrations; run-only options (`createCommits`,
+ * `commitPrefix`, `agentic`, `validate`) only when running migrations. This
+ * mirrors where each option is consumed and avoids tripping the "cannot be
+ * combined with --run-migrations" guards in `parseMigrationsOptions`.
+ *
+ * `mode` is carried as `modeFromConfig` rather than `mode` so it is never
+ * mistaken for an explicit `--mode`: `resolveMode` applies it only when the
+ * target is Nx itself, leaving `nx migrate <non-nx-pkg>` unaffected.
+ */
+function applyNxJsonMigrateDefaults(args, migrateConfig, env = process.env) {
+    if (!migrateConfig) {
+        return args;
+    }
+    const merged = { ...args };
+    // `--run-migrations` with no value is normalized to '' by yargs, so a defined
+    // (even empty-string) value means we're in the run-migrations phase.
+    const isRunMigrations = merged.runMigrations !== undefined;
+    if (isRunMigrations) {
+        if (merged.createCommits === undefined &&
+            migrateConfig.createCommits !== undefined) {
+            assertType(migrateConfig.createCommits, 'boolean', 'createCommits');
+            merged.createCommits = migrateConfig.createCommits;
+        }
+        // `commitPrefix` carries a yargs default, so the default value is
+        // indistinguishable from "not provided" - treat it as not provided so
+        // nx.json can override it.
+        if ((merged.commitPrefix === undefined ||
+            merged.commitPrefix === command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX) &&
+            migrateConfig.commitPrefix !== undefined) {
+            assertType(migrateConfig.commitPrefix, 'string', 'commitPrefix');
+            merged.commitPrefix = migrateConfig.commitPrefix;
+        }
+        if (merged.agentic === undefined && migrateConfig.agentic !== undefined) {
+            assertValidAgentic(migrateConfig.agentic);
+            merged.agentic = (0, cli_args_1.coerceAgenticArg)(migrateConfig.agentic);
+        }
+        if (merged.validate === undefined && migrateConfig.validate !== undefined) {
+            assertType(migrateConfig.validate, 'boolean', 'validate');
+            merged.validate = migrateConfig.validate;
+        }
+    }
+    else {
+        if (merged.mode === undefined && migrateConfig.mode !== undefined) {
+            assertOneOf(migrateConfig.mode, command_object_1.MIGRATE_MODES, 'mode');
+            merged.modeFromConfig = migrateConfig.mode;
+        }
+        // The NX_MULTI_MAJOR_MODE env var is an established per-invocation override,
+        // so it takes precedence over nx.json (CLI flag > env > nx.json > default).
+        if (merged.multiMajorMode === undefined &&
+            !env[MULTI_MAJOR_MODE_ENV] &&
+            migrateConfig.multiMajorMode !== undefined) {
+            assertOneOf(migrateConfig.multiMajorMode, command_object_1.MULTI_MAJOR_MODES, 'multiMajorMode');
+            merged.multiMajorMode = migrateConfig.multiMajorMode;
+        }
+    }
+    return merged;
+}
+function assertOneOf(value, allowed, field) {
+    if (!allowed.includes(value)) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} "${value}". Allowed: ${allowed.join(', ')}.`);
+    }
+}
+function assertType(value, type, field) {
+    if (typeof value !== type) {
+        throw new Error(`Error: Invalid nx.json migrate.${field} ${JSON.stringify(value)}. Expected a ${type}.`);
+    }
+}
+function assertValidAgentic(agentic) {
+    if (typeof agentic === 'boolean') {
+        return;
+    }
+    if (typeof agentic !== 'string' ||
+        !cli_args_1.AGENT_IDS.includes(agentic)) {
+        throw new Error(`Error: Invalid nx.json migrate.agentic "${agentic}". Allowed: ${cli_args_1.AGENT_IDS.join(', ')}, true, false.`);
+    }
+}
+/**
+ * The single authority for the "a custom commit prefix needs commits enabled"
+ * invariant. Run it against the final merged args (after
+ * `applyNxJsonMigrateDefaults`): the yargs `.check()` only sees the CLI args,
+ * but nx.json may enable commits via `createCommits` or `agentic`. The CLI
+ * `.check()` only fast-fails the unrescuable explicit `--no-create-commits`
+ * case; everything else is decided here.
+ */
+function assertCommitPrefixHasCommits(merged) {
+    const { createCommits, commitPrefix, agentic } = merged;
+    if ((0, command_object_1.customCommitPrefixHasNoEffect)({ createCommits, commitPrefix, agentic })) {
+        throw new Error('Error: A custom migrate commit prefix requires commits to be enabled. Set `migrate.createCommits` to `true` in nx.json or pass `--create-commits`.');
+    }
+}

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

@@ -74,6 +74,7 @@ export declare class Migrator {
             factory?: string;
             prompt?: string;
             requires?: Record<string, string>;
+            documentation?: string;
         }[];
     }>;
     private createMigrateJson;
@@ -118,7 +119,9 @@ export declare function resolveCanonicalNxPackage(targetVersion: string): 'nx' |
 export declare function resolveMode(mode: MigrateMode | undefined, targetPackage: string, targetVersion: string, context?: {
     hasFrom: boolean;
     hasExcludeAppliedMigrations: boolean;
-}): Promise<MigrateMode>;
+    installedMajor?: number | null;
+    isV23Plus?: boolean;
+}, configuredMode?: MigrateMode): Promise<MigrateMode>;
 type GenerateMigrations = {
     type: 'generateMigrations';
     targetPackage: string;
@@ -172,6 +175,7 @@ type ExecutableMigration = {
     implementation?: string;
     factory?: string;
     prompt?: string;
+    documentation?: string;
 };
 export { isPromptOnlyMigration, isHybridMigration };
 export declare function resolveAgenticRunId(migrations: ExecutableMigration[]): string;
@@ -235,7 +239,10 @@ export declare function runNxOrAngularMigration(root: string, migration: {
     name: string;
     description?: string;
     version: string;
-}, isVerbose: boolean, captureGeneratorOutput?: boolean): Promise<{
+}, isVerbose: boolean, captureGeneratorOutput?: boolean, resolvedCollection?: {
+    collection: MigrationsJson;
+    collectionPath: string;
+}): Promise<{
     changes: FileChange[];
     nextSteps: string[];
     agentContext: string[];
@@ -258,4 +265,34 @@ export declare function getImplementationPath(collection: MigrationsJson, collec
     path: string;
     fnSymbol: string;
 };
+/**
+ * Resolves a migration's collection once and derives everything the run loop
+ * needs from that single read: the implementation context (`collection` +
+ * `collectionPath`, handed to `runNxOrAngularMigration`) and, for agentic runs,
+ * the workspace-relative documentation path handed to the agent.
+ *
+ * Read fresh per migration (not cached across the loop) so a prior migration's
+ * reinstall is reflected, exactly as before. Error handling matches each field's
+ * role:
+ * - Migrations that run an implementation REQUIRE the collection; an unreadable
+ *   collection throws and aborts that migration (caught by the run loop).
+ * - Prompt-only migrations don't run an implementation, so the collection is
+ *   read only to resolve documentation - a failure there is non-fatal: the
+ *   prompt still runs and the supplementary doc is skipped with a warning.
+ */
+export declare function resolveMigrationForRun(root: string, migration: {
+    package: string;
+    name: string;
+    documentation?: string;
+    implementation?: string;
+    factory?: string;
+    prompt?: string;
+}, resolveDocumentation: boolean): {
+    resolvedCollection?: {
+        collection: MigrationsJson;
+        collectionPath: string;
+    };
+    documentationPath?: string;
+};
+export declare function resolveDocumentationFileToWorkspacePath(root: string, migrationsDir: string, documentation: string): string | undefined;
 export declare function nxCliPath(nxWorkspaceRoot?: string): Promise<string>;

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

@@ -17,6 +17,8 @@ exports.migrate = migrate;
 exports.runMigration = runMigration;
 exports.readMigrationCollection = readMigrationCollection;
 exports.getImplementationPath = getImplementationPath;
+exports.resolveMigrationForRun = resolveMigrationForRun;
+exports.resolveDocumentationFileToWorkspacePath = resolveDocumentationFileToWorkspacePath;
 exports.nxCliPath = nxCliPath;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
@@ -56,6 +58,7 @@ const catalog_1 = require("../../utils/catalog");
 const multi_major_1 = require("./multi-major");
 const prompt_files_1 = require("./prompt-files");
 const command_object_1 = require("./command-object");
+const migrate_config_1 = require("./migrate-config");
 const handoff_gitignore_1 = require("./agentic/handoff-gitignore");
 const migrate_commits_1 = require("./migrate-commits");
 const migrate_output_1 = require("./migrate-output");
@@ -529,28 +532,76 @@ function resolveCanonicalNxPackage(targetVersion) {
 async function resolveMode(mode, targetPackage, targetVersion, context = {
     hasFrom: false,
     hasExcludeAppliedMigrations: false,
-}) {
+}, configuredMode) {
+    // The first-party/third-party split relies on migration metadata that only
+    // exists in Nx v23+. `first-party` needs a v22+ install migrating into a v23+
+    // target; `third-party` catches up deps a prior first-party migration
+    // deferred, so it needs the workspace already on v23+.
+    const installedMajor = context.installedMajor ?? null;
+    const firstPartyAvailable = installedMajor !== null &&
+        installedMajor >= 22 &&
+        context.isV23Plus === true;
+    const thirdPartyAvailable = installedMajor !== null && installedMajor >= 23;
     if (mode) {
+        if ((0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
+            if (mode === 'first-party' && !firstPartyAvailable) {
+                if (context.isV23Plus !== true) {
+                    throw new Error(`Error: '--mode=first-party' requires migrating to Nx v23 or later.`);
+                }
+                throw new Error(`Error: '--mode=first-party' requires the workspace to be on Nx v22 or later. Migrate to the latest Nx v22 first, then to v23 or later.`);
+            }
+            // When the installed version is unknown, defer to the downstream
+            // "requires nx to be installed" check rather than the v23 gate.
+            if (mode === 'third-party' &&
+                installedMajor !== null &&
+                !thirdPartyAvailable) {
+                throw new Error(`Error: '--mode=third-party' requires the workspace to be on Nx v23 or later.`);
+            }
+        }
         return mode;
     }
     if (!(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
         return 'all';
     }
-    if (!process.stdin.isTTY || (0, is_ci_1.isCI)()) {
+    // nx.json `migrate.mode` pre-selects the prompt answer (Nx targets only; non-Nx
+    // returned 'all' above). Honor it only when the v23+ gate makes that mode
+    // available; otherwise warn and fall back to the always-valid 'all'.
+    if (configuredMode) {
+        const configuredAvailable = configuredMode === 'all' ||
+            (configuredMode === 'first-party' && firstPartyAvailable) ||
+            (configuredMode === 'third-party' && thirdPartyAvailable);
+        if (configuredAvailable) {
+            return configuredMode;
+        }
+        output_1.output.warn({
+            title: `The configured nx.json migrate.mode '${configuredMode}' is not available for this migration; falling back to 'all'.`,
+            bodyLines: [
+                `The 'first-party' and 'third-party' modes require Nx v23 or later.`,
+            ],
+        });
         return 'all';
     }
-    const choices = [
-        {
+    const choices = [];
+    if (firstPartyAvailable) {
+        choices.push({
             name: 'first-party',
             message: 'First-party only (Nx and its official packages)',
-        },
-    ];
-    if (!context.hasFrom && !context.hasExcludeAppliedMigrations) {
+        });
+    }
+    if (thirdPartyAvailable &&
+        !context.hasFrom &&
+        !context.hasExcludeAppliedMigrations) {
         choices.push({
             name: 'third-party',
             message: 'Third-party only (deps managed by Nx)',
         });
     }
+    if (!choices.length) {
+        return 'all';
+    }
+    if (!process.stdin.isTTY || (0, is_ci_1.isCI)()) {
+        return 'all';
+    }
     choices.push({
         name: 'all',
         message: 'All (first-party and third-party)',
@@ -656,6 +707,13 @@ async function parseMigrationsOptions(options) {
     });
     targetVersion = multiMajorResult.chosen;
     if (mode === 'third-party') {
+        // `mode` can resolve to third-party via nx.json, which bypasses the early
+        // CLI-only check above; re-assert against the resolved mode.
+        assertThirdPartyModeFlagCompatibility({
+            mode,
+            from: options.from,
+            excludeAppliedMigrations: options.excludeAppliedMigrations,
+        });
         assertThirdPartyTargetBounds({
             targetPackage,
             targetVersion,
@@ -686,9 +744,11 @@ function assertThirdPartyModeFlagCompatibility(options) {
         throw new Error(`Error: '--mode=third-party' cannot be combined with '--exclude-applied-migrations'.`);
     }
 }
-// Defaults target package/version mode-aware (third-party → installed
-// canonical, otherwise nx@latest) and enforces the era gate when --mode
-// is explicit.
+// Resolves the target package/version up front (third-party → installed
+// canonical; otherwise resolves dist-tags so the v23 mode gate reads a concrete
+// major), then resolves the mode and enforces the era gate when --mode is
+// explicit. Bare invocations on a pre-v22 install throw rather than defaulting
+// to `latest` across the major gap into the v23 era.
 async function resolveTargetAndMode(args) {
     const { positional, from, options } = args;
     let targetPackage;
@@ -698,15 +758,55 @@ async function resolveTargetAndMode(args) {
         targetPackage = normalizeSlashes(parsed.targetPackage);
         targetVersion = parsed.targetVersion;
     }
-    // Resolve mode before defaulting target so the default can depend on the
-    // resolved mode (third-party defaults to nx@<installed>; otherwise nx@latest).
-    // For bare invocation, `targetPackage='nx'` and `targetVersion='latest'` are
-    // safe sentinels: `isNxEquivalentTarget` treats the literal `'latest'` as
-    // modern era (semver `lt('latest', '14.0.0-beta.0')` is false).
+    const installed = resolveInstalledCanonical();
+    const installedMajor = installed && (0, semver_1.valid)(installed.version) ? (0, semver_1.major)(installed.version) : null;
+    // `--mode=third-party` anchors the target to the installed version below, so
+    // it never needs a target or dist-tag resolved up front.
+    const isExplicitThirdParty = options.mode === 'third-party';
+    // Bare invocation: restore the requirement to specify a target when on a
+    // pre-v23 install. We can't safely default to `latest` across the major gap
+    // into the new era, and the first-party/third-party functionality isn't
+    // available there anyway.
+    if (!positional && !isExplicitThirdParty) {
+        if (installedMajor === null || installedMajor < 22) {
+            throw new Error(`Provide the package and version to migrate to. E.g., \`nx migrate nx@<version>\`.`);
+        }
+        targetPackage = 'nx';
+        targetVersion = 'latest';
+    }
+    // Explicit dist-tags arrive already resolved from
+    // `parseTargetPackageAndVersion`; only bare invocations and bare package
+    // names (`nx migrate nx`) reach here unresolved.
+    let isV23Plus = false;
+    if (!isExplicitThirdParty &&
+        (0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
+        if (targetVersion && (0, semver_1.valid)(targetVersion)) {
+            isV23Plus = (0, semver_1.major)(targetVersion) >= 23;
+        }
+        else {
+            // Resolving the dist-tag here (rather than only in the multi-major check
+            // as before) just moves the single registry round-trip earlier — the
+            // multi-major check short-circuits on the now-concrete version.
+            const tag = targetVersion;
+            try {
+                targetVersion = await (0, version_utils_1.normalizeVersionWithTagCheck)(targetPackage, tag);
+                isV23Plus = (0, semver_1.valid)(targetVersion) ? (0, semver_1.major)(targetVersion) >= 23 : true;
+            }
+            catch {
+                // Registry unavailable: assume dist-tags resolve to >= v23 (true once
+                // v23 is released) so the gate stays sensible. The retained sentinel
+                // still degrades gracefully downstream (multi-major and the cascade).
+                targetVersion = tag;
+                isV23Plus = true;
+            }
+        }
+    }
     const mode = await resolveMode(options.mode, targetPackage ?? 'nx', targetVersion ?? 'latest', {
         hasFrom: Object.keys(from).length > 0,
         hasExcludeAppliedMigrations: options.excludeAppliedMigrations === true,
-    });
+        installedMajor,
+        isV23Plus,
+    }, options.modeFromConfig);
     let installedNxVersion;
     // For third-party, anchor `targetPackage`/`targetVersion` to the installed
     // canonical when the positional was either omitted or a bare package name
@@ -715,7 +815,6 @@ async function resolveTargetAndMode(args) {
     // the literal `'latest'` that `parseTargetPackageAndVersion` emits for bare
     // package names.
     if (mode === 'third-party' && (!positional || !(0, semver_1.valid)(targetVersion))) {
-        const installed = resolveInstalledCanonical();
         if (!installed) {
             throw new Error(`Error: '--mode=third-party' requires 'nx' (or '@nrwl/workspace' on Nx <14) to be installed in your workspace. Install dependencies first, then re-run.`);
         }
@@ -723,15 +822,6 @@ async function resolveTargetAndMode(args) {
         targetPackage = installed.canonical;
         targetVersion = installed.version;
     }
-    else if (!positional) {
-        // Bare invocation: default to `nx@latest` as a literal sentinel rather
-        // than resolving via the registry here. Multi-major resolves the dist-tag
-        // when needed (and bails gracefully on registry failure), and the cascade
-        // resolves it for the walk (honouring `NX_MIGRATE_SKIP_REGISTRY_FETCH`).
-        // This matches the resilience of `nx migrate nx`.
-        targetPackage = 'nx';
-        targetVersion = 'latest';
-    }
     if (options.mode && !(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
         const isLegacy = (0, version_utils_1.isLegacyEra)(targetVersion);
         const validTargets = isLegacy
@@ -848,14 +938,14 @@ function createInstalledPackageVersionsResolver(root) {
     return getInstalledPackageVersion;
 }
 // testing-fetch-start
-function createFetcher() {
+function createFetcher(pmc) {
     const migrationsCache = {};
     const resolvedVersionCache = {};
     function fetchMigrations(packageName, packageVersion, setCache) {
         if (process.env.NX_MIGRATE_SKIP_REGISTRY_FETCH === 'true') {
             // Skip registry fetch and use installation method directly
             logger_1.logger.info(`Fetching ${packageName}@${packageVersion}`);
-            return getPackageMigrationsUsingInstall(packageName, packageVersion);
+            return getPackageMigrationsUsingInstall(packageName, packageVersion, pmc);
         }
         const cacheKey = packageName + '-' + packageVersion;
         return Promise.resolve(resolvedVersionCache[cacheKey])
@@ -877,7 +967,7 @@ function createFetcher() {
             .catch((e) => {
             logger_1.logger.verbose(`Failed to get migrations from registry for ${packageName}@${packageVersion}: ${e.message}. Falling back to install.`);
             logger_1.logger.info(`Fetching ${packageName}@${packageVersion}`);
-            return getPackageMigrationsUsingInstall(packageName, packageVersion);
+            return getPackageMigrationsUsingInstall(packageName, packageVersion, pmc);
         });
     }
     return function nxMigrateFetcher(packageName, packageVersion) {
@@ -996,18 +1086,17 @@ function createConcurrencyLimiter(concurrency) {
 const installConcurrencyLimit = process.env.NX_MIGRATE_INSTALL_CONCURRENCY
     ? createConcurrencyLimiter(Math.max(1, Math.floor(Number(process.env.NX_MIGRATE_INSTALL_CONCURRENCY)) || 1))
     : null;
-async function getPackageMigrationsUsingInstall(packageName, packageVersion) {
-    const run = () => getPackageMigrationsUsingInstallImpl(packageName, packageVersion);
+async function getPackageMigrationsUsingInstall(packageName, packageVersion, pmc) {
+    const run = () => getPackageMigrationsUsingInstallImpl(packageName, packageVersion, pmc);
     return installConcurrencyLimit ? installConcurrencyLimit(run) : run();
 }
-async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion) {
+async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion, pmc) {
     const { dir, cleanup } = (0, package_manager_1.createTempNpmDirectory)();
     let result;
     if ((0, provenance_1.getNxPackageGroup)().includes(packageName)) {
         await (0, provenance_1.ensurePackageHasProvenance)(packageName, packageVersion);
     }
     try {
-        const pmc = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(dir), dir);
         await execAsync(`${pmc.add} ${packageName}@${packageVersion}`, {
             cwd: dir,
             env: {
@@ -1031,7 +1120,6 @@ async function getPackageMigrationsUsingInstallImpl(packageName, packageVersion)
         };
     }
     catch (e) {
-        const pmc = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(dir), dir);
         throw new Error([
             `Failed to fetch migrations for ${packageName}@${packageVersion}`,
             formatCommandFailure(`${pmc.add} ${packageName}@${packageVersion}`, e),
@@ -1218,7 +1306,7 @@ async function generateMigrationsJsonAndUpdatePackageJson(root, opts) {
         }
         logger_1.logger.info(`Fetching meta data about packages.`);
         logger_1.logger.info(`It may take a few minutes.`);
-        const fetch = createFetcher();
+        const fetch = createFetcher(pmc);
         let firstPartyPackages;
         if (mode === 'first-party' || mode === 'third-party') {
             // `@nx/workspace` is version-synced with `nx` and declares an
@@ -1572,9 +1660,16 @@ function resolveCreateCommits(args) {
         }
         return { effective: true, agenticHasDiffContext: true };
     }
+    // Commits aren't enabled here. A custom prefix only reaches this path via
+    // nx.json (e.g. `migrate.commitPrefix` + `migrate.agentic` when the agentic
+    // flow resolves to disabled); surface that it has no effect rather than
+    // dropping it silently.
     return {
         effective: createCommits === true,
         agenticHasDiffContext: false,
+        warning: commitPrefixIsCustom && createCommits !== true
+            ? 'A custom migrate commit prefix is configured, but commits are not enabled for this run, so it has no effect. Set `migrate.createCommits` to `true` (or pass `--create-commits`) to create a commit per migration.'
+            : undefined,
     };
 }
 /**
@@ -1716,6 +1811,11 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
         // already-dirty shared file like `package.json`) doesn't collapse.
         const baselineWorkingTreeSnapshot = (0, git_utils_1.getUncommittedChangesSnapshot)(root);
         try {
+            // Read this migration's collection once and derive everything from it:
+            // the implementation context (passed to runNxOrAngularMigration) and the
+            // documentation path (passed to the agent). Read fresh per iteration so a
+            // prior migration's reinstall is reflected.
+            const { resolvedCollection, documentationPath } = resolveMigrationForRun(root, m, !!agenticRun);
             let outcome;
             let commit = { kind: 'none' };
             if ((0, migration_shape_1.isPromptOnlyMigration)(m)) {
@@ -1726,6 +1826,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         agentic: agenticRun.agentic,
                         runDir: agenticRun.runDir,
                         installDepsIfChanged,
+                        documentationPath,
                     });
                     commit = await attemptMigrationCommit(m);
                     (0, migrate_output_1.logAgenticSuccessOutcome)(stepResult.ambiguous ? 'Marked complete by user' : 'Applied', commit.kind === 'landed' ? commit.sha : null, stepResult.summary);
@@ -1740,7 +1841,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
             }
             else if ((0, migration_shape_1.isHybridMigration)(m)) {
                 const { changes, nextSteps, agentContext, logs, madeChanges } = await runNxOrAngularMigration(root, m, isVerbose, 
-                /* captureGeneratorOutput: */ !!agenticRun);
+                /* captureGeneratorOutput: */ !!agenticRun, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
                 if (agenticRun) {
                     // Install any deps the deterministic phase added/bumped before the
@@ -1753,6 +1854,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         agentic: agenticRun.agentic,
                         runDir: agenticRun.runDir,
                         installDepsIfChanged,
+                        documentationPath,
                         implContext: {
                             logs,
                             changes,
@@ -1801,7 +1903,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                 // changes uncommitted in the working tree for the user to review.
                 const validationRun = agenticRun && shouldRunValidation ? agenticRun : undefined;
                 const { changes, nextSteps, agentContext, logs, madeChanges } = await runNxOrAngularMigration(root, m, isVerbose, 
-                /* captureGeneratorOutput: */ !!validationRun);
+                /* captureGeneratorOutput: */ !!validationRun, resolvedCollection);
                 migrationEmittedNextSteps.push(...nextSteps);
                 const canRunValidation = !!validationRun && changes.length > 0;
                 if (canRunValidation) {
@@ -1814,6 +1916,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         agentic: validationRun.agentic,
                         runDir: validationRun.runDir,
                         installDepsIfChanged,
+                        documentationPath,
                         implContext: {
                             logs,
                             changes,
@@ -1957,8 +2060,8 @@ function logSkippedPostMigrationInstall(root) {
         bodyLines: [`Run "${installCommand}" to install the updated dependencies.`],
     });
 }
-async function runNxOrAngularMigration(root, migration, isVerbose, captureGeneratorOutput = false) {
-    const { collection, collectionPath } = readMigrationCollection(migration.package, root);
+async function runNxOrAngularMigration(root, migration, isVerbose, captureGeneratorOutput = false, resolvedCollection) {
+    const { collection, collectionPath } = resolvedCollection ?? readMigrationCollection(migration.package, root);
     let changes = [];
     let nextSteps = [];
     let agentContext = [];
@@ -2219,13 +2322,15 @@ function filterStrings(value) {
 async function migrate(root, args, rawArgs) {
     await client_1.daemonClient.stop();
     return (0, handle_errors_1.handleErrors)(process.env.NX_VERBOSE_LOGGING === 'true', async () => {
-        const opts = await parseMigrationsOptions(args);
+        const mergedArgs = (0, migrate_config_1.applyNxJsonMigrateDefaults)(args, (0, configuration_1.readNxJson)().migrate);
+        (0, migrate_config_1.assertCommitPrefixHasCommits)(mergedArgs);
+        const opts = await parseMigrationsOptions(mergedArgs);
         if (opts.type === 'generateMigrations') {
             await generateMigrationsJsonAndUpdatePackageJson(root, opts);
         }
         else {
             try {
-                return await runMigrations(root, opts, rawArgs, args['verbose'], args['createCommits'], args['commitPrefix'], args['skipInstall']);
+                return await runMigrations(root, opts, rawArgs, mergedArgs['verbose'], mergedArgs['createCommits'], mergedArgs['commitPrefix'] ?? command_object_1.DEFAULT_MIGRATION_COMMIT_PREFIX, mergedArgs['skipInstall']);
             }
             catch (e) {
                 // The remediation guidance is already logged by `runInstall`; swallow
@@ -2297,6 +2402,63 @@ function getImplementationPath(collection, collectionPath, name, migrationVersio
     }
     return { path: implPath, fnSymbol };
 }
+/**
+ * Resolves a migration's collection once and derives everything the run loop
+ * needs from that single read: the implementation context (`collection` +
+ * `collectionPath`, handed to `runNxOrAngularMigration`) and, for agentic runs,
+ * the workspace-relative documentation path handed to the agent.
+ *
+ * Read fresh per migration (not cached across the loop) so a prior migration's
+ * reinstall is reflected, exactly as before. Error handling matches each field's
+ * role:
+ * - Migrations that run an implementation REQUIRE the collection; an unreadable
+ *   collection throws and aborts that migration (caught by the run loop).
+ * - Prompt-only migrations don't run an implementation, so the collection is
+ *   read only to resolve documentation - a failure there is non-fatal: the
+ *   prompt still runs and the supplementary doc is skipped with a warning.
+ */
+function resolveMigrationForRun(root, migration, resolveDocumentation) {
+    let resolvedCollection;
+    if (!(0, migration_shape_1.isPromptOnlyMigration)(migration)) {
+        resolvedCollection = readMigrationCollection(migration.package, root);
+    }
+    else if (resolveDocumentation && migration.documentation) {
+        try {
+            resolvedCollection = readMigrationCollection(migration.package, root);
+        }
+        catch {
+            // Non-fatal: documentation is supplementary; the warning below fires.
+        }
+    }
+    let documentationPath;
+    if (resolveDocumentation && migration.documentation) {
+        documentationPath = resolvedCollection
+            ? resolveDocumentationFileToWorkspacePath(root, (0, path_1.dirname)(resolvedCollection.collectionPath), migration.documentation)
+            : undefined;
+        if (!documentationPath) {
+            logger_1.logger.warn(`Could not resolve the "documentation" file "${migration.documentation}" declared for migration "${migration.package}: ${migration.name}". It will be skipped as additional context for the AI agent.`);
+        }
+    }
+    return { resolvedCollection, documentationPath };
+}
+// Resolves a `documentation` path (relative to the package's migrations dir) to
+// a workspace-relative path - or the absolute path when it resolves outside the
+// workspace (unusual hoisted/symlinked layouts). The agent runs with cwd =
+// workspace root, so the workspace-relative form is preferred. Returns
+// undefined when the file can't be resolved.
+function resolveDocumentationFileToWorkspacePath(root, migrationsDir, documentation) {
+    let documentationFile;
+    try {
+        documentationFile = require.resolve(documentation, {
+            paths: [migrationsDir],
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const relativePath = (0, path_1.relative)(root, documentationFile);
+    return relativePath.startsWith('..') ? documentationFile : relativePath;
+}
 class MigrationImplementationMissingError extends Error {
     constructor(baseMessage, collectionPath, migrationVersion) {
         super(buildMigrationMissingMessage(baseMessage, collectionPath, migrationVersion));

package/dist/src/command-line/migrate/multi-major.js

@@ -149,8 +149,11 @@ async function maybePromptOrWarnMultiMajorMigration(args) {
         resolveLatestStableInMajor(targetPackage, installedMajor + 1),
     ]);
     // Only suggest the current-major latest when there's at least a minor
-    // delta — a same-minor patch bump isn't a meaningful incremental step.
-    const showCurrent = latestInCurrent &&
+    // delta — a same-minor patch bump isn't a meaningful incremental step. Skip
+    // major 22 (last pre-v23) entirely: a 22.x step is the only sub-v23 option
+    // and conflicts with the mode gate already decided against the v23+ target.
+    const showCurrent = installedMajor !== 22 &&
+        latestInCurrent &&
         (0, semver_1.gt)(latestInCurrent, installed) &&
         (0, semver_1.minor)(latestInCurrent) > (0, semver_1.minor)(installed)
         ? latestInCurrent

package/dist/src/command-line/release/changelog/version-plan-filtering.d.ts

@@ -16,7 +16,7 @@ export declare function filterVersionPlansByCommitRange(versionPlans: RawVersion
  * Resolves the "from SHA" for changelog purposes.
  * This determines the starting point for changelog generation and optional version plan filtering.
  */
-export declare function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatternValues, checkAllBranchesWhen, preid, requireSemver, strictPreid, useAutomaticFromRef, resolveRepositoryTags, }: {
+export declare function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatternValues, checkAllBranchesWhen, preid, requireSemver, strictPreid, useAutomaticFromRef, resolveRepositoryTags, projectRoot, }: {
     fromRef?: string;
     tagPattern: string;
     tagPatternValues: Record<string, string>;
@@ -26,6 +26,8 @@ export declare function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatter
     strictPreid: boolean;
     useAutomaticFromRef: boolean;
     resolveRepositoryTags: RepoGitTags['resolveTags'];
+    /** When provided, scopes the fallback to the project's first commit instead of the repo's first commit */
+    projectRoot?: string;
 }): Promise<string | null>;
 /**
  * Helper function for workspace-level "from SHA" resolution.