nx 23.0.0-beta.21 → 23.0.0-beta.22

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,7 @@ 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>;
+}, configuredMode?: MigrateMode): Promise<MigrateMode>;
 type GenerateMigrations = {
     type: 'generateMigrations';
     targetPackage: string;
@@ -172,6 +173,7 @@ type ExecutableMigration = {
     implementation?: string;
     factory?: string;
     prompt?: string;
+    documentation?: string;
 };
 export { isPromptOnlyMigration, isHybridMigration };
 export declare function resolveAgenticRunId(migrations: ExecutableMigration[]): string;
@@ -235,7 +237,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 +263,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,13 +532,18 @@ function resolveCanonicalNxPackage(targetVersion) {
 async function resolveMode(mode, targetPackage, targetVersion, context = {
     hasFrom: false,
     hasExcludeAppliedMigrations: false,
-}) {
+}, configuredMode) {
     if (mode) {
         return mode;
     }
     if (!(0, version_utils_1.isNxEquivalentTarget)(targetPackage, targetVersion)) {
         return 'all';
     }
+    // nx.json `migrate.mode` pre-selects the value the interactive prompt would
+    // ask for; it applies only to Nx targets (non-Nx returned 'all' above).
+    if (configuredMode) {
+        return configuredMode;
+    }
     if (!process.stdin.isTTY || (0, is_ci_1.isCI)()) {
         return 'all';
     }
@@ -656,6 +664,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,
@@ -706,7 +721,7 @@ async function resolveTargetAndMode(args) {
     const mode = await resolveMode(options.mode, targetPackage ?? 'nx', targetVersion ?? 'latest', {
         hasFrom: Object.keys(from).length > 0,
         hasExcludeAppliedMigrations: options.excludeAppliedMigrations === true,
-    });
+    }, 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
@@ -1572,9 +1587,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 +1738,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 +1753,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 +1768,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 +1781,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         agentic: agenticRun.agentic,
                         runDir: agenticRun.runDir,
                         installDepsIfChanged,
+                        documentationPath,
                         implContext: {
                             logs,
                             changes,
@@ -1801,7 +1830,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 +1843,7 @@ async function executeMigrations(root, migrations, isVerbose, shouldCreateCommit
                         agentic: validationRun.agentic,
                         runDir: validationRun.runDir,
                         installDepsIfChanged,
+                        documentationPath,
                         implContext: {
                             logs,
                             changes,
@@ -1957,8 +1987,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 +2249,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 +2329,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/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.

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

@@ -89,7 +89,7 @@ async function getFilesAddedInCommitRange(fromSHA, toSHA, isVerbose) {
  * Resolves the "from SHA" for changelog purposes.
  * This determines the starting point for changelog generation and optional version plan filtering.
  */
-async function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatternValues, checkAllBranchesWhen, preid, requireSemver, strictPreid, useAutomaticFromRef, resolveRepositoryTags, }) {
+async function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatternValues, checkAllBranchesWhen, preid, requireSemver, strictPreid, useAutomaticFromRef, resolveRepositoryTags, projectRoot, }) {
     // If user provided a from ref, resolve it to a SHA
     if (fromRef) {
         return await (0, git_1.getCommitHash)(fromRef);
@@ -104,9 +104,13 @@ async function resolveChangelogFromSHA({ fromRef, tagPattern, tagPatternValues,
     if (latestTag?.tag) {
         return await (0, git_1.getCommitHash)(latestTag.tag);
     }
-    // Finally, if automatic from ref is enabled, use the first commit as a fallback
+    // Finally, if automatic from ref is enabled, use the first commit as a fallback.
+    // When a projectRoot is provided, scope the fallback to the project's first commit
+    // to avoid scanning the entire repo history for projects added after the repo was created.
     if (useAutomaticFromRef) {
-        return await (0, git_1.getFirstGitCommit)();
+        return projectRoot
+            ? await (0, git_1.getFirstProjectCommit)(projectRoot)
+            : await (0, git_1.getFirstGitCommit)();
     }
     return null;
 }

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

@@ -1,5 +1,6 @@
 import { NxReleaseConfiguration } from '../../config/nx-json';
 import { ChangelogOptions } from './command-object';
+import { NxReleaseConfig } from './config/config';
 import { ReleaseVersion } from './utils/shared';
 export interface NxReleaseChangelogResult {
     workspaceChangelog?: {
@@ -17,5 +18,11 @@ export interface NxReleaseChangelogResult {
 }
 export type { ChangelogChange } from './changelog/version-plan-utils';
 export type PostGitTask = (latestCommit: string) => Promise<void>;
+/**
+ * Determines whether a changelog configuration will actually produce any output.
+ * A changelog config is effectively enabled when it would produce a changelog file
+ * or create a remote release.
+ */
+export declare function isChangelogEffectivelyEnabled(config?: NxReleaseConfig['changelog']['workspaceChangelog'] | NxReleaseConfig['groups'][string]['changelog']): boolean | undefined;
 export declare const releaseChangelogCLIHandler: (args: ChangelogOptions) => Promise<number>;
 export declare function createAPI(overrideReleaseConfig: NxReleaseConfiguration, ignoreNxJsonConfig: boolean): (args: ChangelogOptions) => Promise<NxReleaseChangelogResult>;

package/dist/src/command-line/release/changelog.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.releaseChangelogCLIHandler = void 0;
+exports.isChangelogEffectivelyEnabled = isChangelogEffectivelyEnabled;
 exports.createAPI = createAPI;
 const tslib_1 = require("tslib");
 const pc = tslib_1.__importStar(require("picocolors"));
@@ -35,6 +36,17 @@ const resolve_changelog_renderer_1 = require("./utils/resolve-changelog-renderer
 const resolve_nx_json_error_message_1 = require("./utils/resolve-nx-json-error-message");
 const shared_1 = require("./utils/shared");
 const version_plan_utils_2 = require("./utils/version-plan-utils");
+/**
+ * Determines whether a changelog configuration will actually produce any output.
+ * A changelog config is effectively enabled when it would produce a changelog file
+ * or create a remote release.
+ */
+function isChangelogEffectivelyEnabled(config) {
+    if (!config) {
+        return false;
+    }
+    return config.file !== false || config.createRelease !== false;
+}
 const releaseChangelogCLIHandler = (args) => (0, handle_errors_1.handleErrors)(args.verbose, () => createAPI({}, false)(args));
 exports.releaseChangelogCLIHandler = releaseChangelogCLIHandler;
 function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
@@ -100,13 +112,8 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             process.env.NX_RELEASE_INTERNAL_SUPPRESS_FILTER_LOG !== 'true') {
             output_1.output.note(releaseGraph.filterLog);
         }
-        let rawVersionPlans = await (0, version_plans_1.readRawVersionPlans)();
-        if (args.deleteVersionPlans === undefined) {
-            // default to deleting version plans in this command instead of after versioning
-            args.deleteVersionPlans = true;
-        }
-        const changelogGenerationEnabled = !!nxReleaseConfig.changelog.workspaceChangelog ||
-            Object.values(nxReleaseConfig.groups).some((g) => g.changelog);
+        const changelogGenerationEnabled = isChangelogEffectivelyEnabled(nxReleaseConfig.changelog.workspaceChangelog) ||
+            Object.values(nxReleaseConfig.groups).some((g) => isChangelogEffectivelyEnabled(g.changelog));
         if (!changelogGenerationEnabled) {
             output_1.output.warn({
                 title: `Changelogs are disabled. No changelog entries will be generated`,
@@ -116,6 +123,11 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             });
             return {};
         }
+        let rawVersionPlans = await (0, version_plans_1.readRawVersionPlans)();
+        if (args.deleteVersionPlans === undefined) {
+            // default to deleting version plans in this command instead of after versioning
+            args.deleteVersionPlans = true;
+        }
         const useAutomaticFromRef = nxReleaseConfig.changelog?.automaticFromRef || args.firstRelease;
         /**
          * For determining the versions to use within changelog files, there are a few different possibilities:
@@ -214,7 +226,7 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             fromSHACache.set('workspace', fromSHA);
         }
         // Helper function to get cached from SHA or resolve and cache it
-        const getCachedFromSHA = async (cacheKey, pattern, templateValues, preid, checkAllBranchesWhen, requireSemver, strictPreid) => {
+        const getCachedFromSHA = async (cacheKey, pattern, templateValues, preid, checkAllBranchesWhen, requireSemver, strictPreid, projectRoot) => {
             if (fromSHACache.has(cacheKey)) {
                 return fromSHACache.get(cacheKey);
             }
@@ -228,6 +240,7 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
                 requireSemver,
                 strictPreid,
                 useAutomaticFromRef,
+                projectRoot,
             });
             fromSHACache.set(cacheKey, sha);
             return sha;
@@ -296,7 +309,7 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
                         const fromSHA = await getCachedFromSHA(projectCacheKey, releaseGroup.releaseTag.pattern, {
                             projectName: project.name,
                             releaseGroupName: releaseGroup.name,
-                        }, projectsPreid[project.name], releaseGroup.releaseTag.checkAllBranchesWhen, releaseGroup.releaseTag.requireSemver, releaseGroup.releaseTag.strictPreid);
+                        }, projectsPreid[project.name], releaseGroup.releaseTag.checkAllBranchesWhen, releaseGroup.releaseTag.requireSemver, releaseGroup.releaseTag.strictPreid, project.data.root);
                         let commits;
                         let fromRef = fromSHA;
                         if (!fromRef && useAutomaticFromRef) {

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

@@ -84,19 +84,6 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
         });
         // Suppress the filter log for the changelog command as it would have already been printed by the version command
         process.env.NX_RELEASE_INTERNAL_SUPPRESS_FILTER_LOG = 'true';
-        const changelogResult = await releaseChangelog({
-            ...args,
-            // Re-use existing release graph
-            releaseGraph,
-            versionData: projectsVersionData,
-            version: workspaceVersion,
-            stageChanges: shouldStage,
-            gitCommit: false,
-            gitTag: false,
-            gitPush: false,
-            createRelease: false,
-            deleteVersionPlans: false,
-        });
         await (0, version_plans_1.setResolvedVersionPlansOnGroups)(rawVersionPlans, releaseGraph.releaseGroups, Object.keys(projectGraph.nodes), args.verbose);
         // Validate version plans against the filter after resolution
         const versionPlanValidationError = (0, version_plan_utils_1.validateResolvedVersionPlansAgainstFilter)(releaseGraph.releaseGroups, releaseGraph.releaseGroupToFilteredProjects);
@@ -150,6 +137,27 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
                 verbose: args.verbose,
             });
         }
+        // Check if any changelog generation is actually enabled before calling releaseChangelog,
+        // to avoid expensive operations (project graph recreation, git log, etc.) when changelogs are disabled
+        const changelogGenerationEnabled = (0, changelog_1.isChangelogEffectivelyEnabled)(nxReleaseConfig.changelog.workspaceChangelog) ||
+            releaseGraph.releaseGroups.some((g) => (0, changelog_1.isChangelogEffectivelyEnabled)(g.changelog));
+        // Run changelog generation before git commit/tag so that changelog files are
+        // included in the same commit as the version bump
+        const changelogResult = changelogGenerationEnabled
+            ? await releaseChangelog({
+                ...args,
+                // Re-use existing release graph
+                releaseGraph,
+                versionData: projectsVersionData,
+                version: workspaceVersion,
+                stageChanges: shouldStage,
+                gitCommit: false,
+                gitTag: false,
+                gitPush: false,
+                createRelease: false,
+                deleteVersionPlans: false,
+            })
+            : undefined;
         if (shouldCommit) {
             output_1.output.logSingleLine(`Committing changes with git`);
             const commitMessage = nxReleaseConfig.git.commitMessage;
@@ -190,51 +198,53 @@ function createAPI(overrideReleaseConfig, ignoreNxJsonConfig) {
             });
             hasPushedChanges = true;
         }
-        let latestCommit;
-        if (shouldCreateWorkspaceRemoteRelease &&
-            changelogResult.workspaceChangelog) {
-            const remoteReleaseClient = await (0, remote_release_client_1.createRemoteReleaseClient)(
-            // shouldCreateWorkspaceRemoteRelease() ensures that the createRelease property exists and is not false
-            nxReleaseConfig.changelog.workspaceChangelog
-                .createRelease);
-            if (!hasPushedChanges) {
-                throw new Error(`It is not possible to create a ${remoteReleaseClient.remoteReleaseProviderName} release for the workspace without pushing the changes to the remote, please ensure that you have not disabled git push in your nx release config`);
-            }
-            output_1.output.logSingleLine(`Creating ${remoteReleaseClient.remoteReleaseProviderName} Release`);
-            latestCommit = await (0, git_1.getCommitHash)('HEAD');
-            await remoteReleaseClient.createOrUpdateRelease(changelogResult.workspaceChangelog.releaseVersion, changelogResult.workspaceChangelog.contents, latestCommit, { dryRun: args.dryRun });
-        }
-        for (const releaseGroupName of releaseGraph.sortedReleaseGroups) {
-            const releaseGroup = releaseGraph.releaseGroups.find((g) => g.name === releaseGroupName);
-            if (!releaseGroup) {
-                continue;
-            }
-            const shouldCreateProjectRemoteReleases = shouldCreateRemoteRelease(releaseGroup.changelog);
-            if (shouldCreateProjectRemoteReleases &&
-                changelogResult.projectChangelogs) {
+        if (changelogResult) {
+            let latestCommit;
+            if (shouldCreateWorkspaceRemoteRelease &&
+                changelogResult.workspaceChangelog) {
                 const remoteReleaseClient = await (0, remote_release_client_1.createRemoteReleaseClient)(
-                // shouldCreateProjectRemoteReleases() ensures that the createRelease property exists and is not false
-                releaseGroup.changelog
+                // shouldCreateWorkspaceRemoteRelease() ensures that the createRelease property exists and is not false
+                nxReleaseConfig.changelog.workspaceChangelog
                     .createRelease);
-                const projects = args.projects?.length
-                    ? // If the user has passed a list of projects, we need to use the filtered list of projects within the release group
-                        Array.from(releaseGraph.releaseGroupToFilteredProjects.get(releaseGroup))
-                    : // Otherwise, we use the full list of projects within the release group
-                        releaseGroup.projects;
-                const projectNodes = projects.map((name) => projectGraph.nodes[name]);
-                for (const project of projectNodes) {
-                    const changelog = changelogResult.projectChangelogs[project.name];
-                    if (!changelog) {
-                        continue;
-                    }
-                    if (!hasPushedChanges) {
-                        throw new Error(`It is not possible to create a ${remoteReleaseClient.remoteReleaseProviderName} release for the project without pushing the changes to the remote, please ensure that you have not disabled git push in your nx release config`);
-                    }
-                    output_1.output.logSingleLine(`Creating ${remoteReleaseClient.remoteReleaseProviderName} Release`);
-                    if (!latestCommit) {
-                        latestCommit = await (0, git_1.getCommitHash)('HEAD');
+                if (!hasPushedChanges) {
+                    throw new Error(`It is not possible to create a ${remoteReleaseClient.remoteReleaseProviderName} release for the workspace without pushing the changes to the remote, please ensure that you have not disabled git push in your nx release config`);
+                }
+                output_1.output.logSingleLine(`Creating ${remoteReleaseClient.remoteReleaseProviderName} Release`);
+                latestCommit = await (0, git_1.getCommitHash)('HEAD');
+                await remoteReleaseClient.createOrUpdateRelease(changelogResult.workspaceChangelog.releaseVersion, changelogResult.workspaceChangelog.contents, latestCommit, { dryRun: args.dryRun });
+            }
+            for (const releaseGroupName of releaseGraph.sortedReleaseGroups) {
+                const releaseGroup = releaseGraph.releaseGroups.find((g) => g.name === releaseGroupName);
+                if (!releaseGroup) {
+                    continue;
+                }
+                const shouldCreateProjectRemoteReleases = shouldCreateRemoteRelease(releaseGroup.changelog);
+                if (shouldCreateProjectRemoteReleases &&
+                    changelogResult.projectChangelogs) {
+                    const remoteReleaseClient = await (0, remote_release_client_1.createRemoteReleaseClient)(
+                    // shouldCreateProjectRemoteReleases() ensures that the createRelease property exists and is not false
+                    releaseGroup.changelog
+                        .createRelease);
+                    const projects = args.projects?.length
+                        ? // If the user has passed a list of projects, we need to use the filtered list of projects within the release group
+                            Array.from(releaseGraph.releaseGroupToFilteredProjects.get(releaseGroup))
+                        : // Otherwise, we use the full list of projects within the release group
+                            releaseGroup.projects;
+                    const projectNodes = projects.map((name) => projectGraph.nodes[name]);
+                    for (const project of projectNodes) {
+                        const changelog = changelogResult.projectChangelogs[project.name];
+                        if (!changelog) {
+                            continue;
+                        }
+                        if (!hasPushedChanges) {
+                            throw new Error(`It is not possible to create a ${remoteReleaseClient.remoteReleaseProviderName} release for the project without pushing the changes to the remote, please ensure that you have not disabled git push in your nx release config`);
+                        }
+                        output_1.output.logSingleLine(`Creating ${remoteReleaseClient.remoteReleaseProviderName} Release`);
+                        if (!latestCommit) {
+                            latestCommit = await (0, git_1.getCommitHash)('HEAD');
+                        }
+                        await remoteReleaseClient.createOrUpdateRelease(changelog.releaseVersion, changelog.contents, latestCommit, { dryRun: args.dryRun });
                     }
-                    await remoteReleaseClient.createOrUpdateRelease(changelog.releaseVersion, changelog.contents, latestCommit, { dryRun: args.dryRun });
                 }
             }
         }

package/dist/src/command-line/release/utils/git.d.ts

@@ -118,3 +118,9 @@ export declare function parseVersionPlanCommit(commit: RawGitCommit): {
 export declare function parseGitCommit(commit: RawGitCommit): GitCommit | null;
 export declare function getCommitHash(ref: string): Promise<string>;
 export declare function getFirstGitCommit(): Promise<string>;
+/**
+ * Returns the parent of the first commit that touched the given project root,
+ * so that `from..HEAD` ranges include the project's creation commit.
+ * Falls back to getFirstGitCommit() if the project history cannot be determined.
+ */
+export declare function getFirstProjectCommit(projectRoot: string): Promise<string>;

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

@@ -15,6 +15,7 @@ exports.parseVersionPlanCommit = parseVersionPlanCommit;
 exports.parseGitCommit = parseGitCommit;
 exports.getCommitHash = getCommitHash;
 exports.getFirstGitCommit = getFirstGitCommit;
+exports.getFirstProjectCommit = getFirstProjectCommit;
 /**
  * Special thanks to changelogen for the original inspiration for many of these utilities:
  * https://github.com/unjs/changelogen
@@ -542,6 +543,38 @@ async function getFirstGitCommit() {
         throw new Error(`Unable to find first commit in git history`);
     }
 }
+/**
+ * Returns the parent of the first commit that touched the given project root,
+ * so that `from..HEAD` ranges include the project's creation commit.
+ * Falls back to getFirstGitCommit() if the project history cannot be determined.
+ */
+async function getFirstProjectCommit(projectRoot) {
+    try {
+        const result = (await (0, exec_command_1.execCommand)('git', [
+            'rev-list',
+            '--reverse',
+            'HEAD',
+            '--first-parent',
+            '--',
+            projectRoot,
+        ])).trim();
+        const firstCommit = result.split('\n')[0];
+        if (firstCommit) {
+            // Return the parent so the creation commit is included in from..to ranges
+            try {
+                return (await (0, exec_command_1.execCommand)('git', ['rev-parse', `${firstCommit}~1`])).trim();
+            }
+            catch {
+                // No parent (project was added in the repo's very first commit)
+                return firstCommit;
+            }
+        }
+    }
+    catch {
+        // fall through to fallback
+    }
+    return getFirstGitCommit();
+}
 async function getGitRoot() {
     try {
         return (await (0, exec_command_1.execCommand)('git', ['rev-parse', '--show-toplevel'])).trim();