nx 19.6.0-canary.20240806-a3869a8 → 19.6.0-canary.20240809-d3747e0

package/src/command-line/release/command-object.d.ts

@@ -6,6 +6,7 @@ export interface NxReleaseArgs {
     projects?: string[];
     dryRun?: boolean;
     verbose?: boolean;
+    printConfig?: boolean | 'debug';
 }
 interface GitCommitAndTagOptions {
     stageChanges?: boolean;

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

@@ -39,6 +39,20 @@ exports.yargsReleaseCommand = {
         .option('verbose', {
         type: 'boolean',
         describe: 'Prints additional information about the commands (e.g., stack traces)',
+    })
+        // NOTE: The camel case format is required for the coerce() function to be called correctly. It still supports --print-config casing.
+        .option('printConfig', {
+        type: 'string',
+        describe: 'Print the resolved nx release configuration that would be used for the current command and then exit',
+        coerce: (val) => {
+            if (val === '') {
+                return true;
+            }
+            if (val === 'false') {
+                return false;
+            }
+            return val;
+        },
     })
         .check((argv) => {
         if (argv.groups && argv.projects) {

package/src/command-line/release/config/deep-merge-json.d.ts

@@ -0,0 +1 @@
+export declare function deepMergeJson<T extends Record<string, any>>(target: T, source: T): T;

package/src/command-line/release/config/deep-merge-json.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMergeJson = deepMergeJson;
+function isObject(obj) {
+    return obj && typeof obj === 'object' && !Array.isArray(obj);
+}
+function deepMergeJson(target, source) {
+    try {
+        // Ensure both objects are valid JSON before attempting to merge values
+        JSON.parse(JSON.stringify(source));
+        JSON.parse(JSON.stringify(target));
+        for (const key in source) {
+            if (isObject(source[key])) {
+                if (!target[key]) {
+                    Object.assign(target, { [key]: {} });
+                }
+                deepMergeJson(target[key], source[key]);
+            }
+            else {
+                Object.assign(target, { [key]: source[key] });
+            }
+        }
+        return target;
+    }
+    catch {
+        throw new Error('Invalid JSON was provided');
+    }
+}

package/src/command-line/release/config/version-plans.d.ts

@@ -15,6 +15,11 @@ export interface VersionPlan extends VersionPlanFile {
 }
 export interface GroupVersionPlan extends VersionPlan {
     groupVersionBump: ReleaseType;
+    /**
+     * Will not be set if the group name was the trigger, otherwise will be a list of
+     * all the individual project names explicitly found in the version plan file.
+     */
+    triggeredByProjects?: string[];
 }
 export interface ProjectsVersionPlan extends VersionPlan {
     projectVersionBumps: Record<string, ReleaseType>;

package/src/command-line/release/config/version-plans.js

@@ -29,7 +29,7 @@ async function readRawVersionPlans() {
             relativePath: (0, path_1.join)(versionPlansDirectory, versionPlanFile),
             fileName: versionPlanFile,
             content: parsedContent.attributes,
-            message: getSingleLineMessage(parsedContent.body),
+            message: parsedContent.body,
             createdOnMs: versionPlanStats.birthtimeMs,
         });
     }
@@ -39,6 +39,9 @@ function setVersionPlansOnGroups(rawVersionPlans, releaseGroups, allProjectNames
     const groupsByName = releaseGroups.reduce((acc, group) => acc.set(group.name, group), new Map());
     const isDefaultGroup = isDefault(releaseGroups);
     for (const rawVersionPlan of rawVersionPlans) {
+        if (!rawVersionPlan.message) {
+            throw new Error(`Please add a changelog message to version plan: '${rawVersionPlan.fileName}'`);
+        }
         for (const [key, value] of Object.entries(rawVersionPlan.content)) {
             if (groupsByName.has(key)) {
                 const group = groupsByName.get(key);
@@ -143,6 +146,9 @@ function setVersionPlansOnGroups(rawVersionPlans, releaseGroups, allProjectNames
                                 throw new Error(`Found a version bump for project '${key}' in '${rawVersionPlan.fileName}' that conflicts with another project's version bump in the same release group '${groupForProject.name}'. When the group is in fixed versioning mode, all projects' version bumps within the same group must match.`);
                             }
                         }
+                        else {
+                            existingPlan.triggeredByProjects.push(key);
+                        }
                     }
                     else {
                         groupForProject.versionPlans.push({
@@ -152,7 +158,9 @@ function setVersionPlansOnGroups(rawVersionPlans, releaseGroups, allProjectNames
                             createdOnMs: rawVersionPlan.createdOnMs,
                             message: rawVersionPlan.message,
                             // This is a fixed group, so the version bump is for the group, even if a project within it was specified
+                            // but we track the projects that triggered the version bump so that we can accurately produce changelog entries.
                             groupVersionBump: value,
+                            triggeredByProjects: [key],
                         });
                     }
                 }
@@ -177,7 +185,3 @@ function getVersionPlansAbsolutePath() {
 function isReleaseType(value) {
     return semver_1.RELEASE_TYPES.includes(value);
 }
-// changelog messages may only be a single line long, so ignore anything else
-function getSingleLineMessage(message) {
-    return message.trim().split('\n')[0];
-}

package/src/command-line/release/index.d.ts

@@ -1,16 +1,28 @@
+import type { NxReleaseConfiguration } from '../../config/nx-json';
 /**
  * @public
  */
-export { releaseChangelog } from './changelog';
+export declare class ReleaseClient {
+    private overrideReleaseConfig;
+    releaseChangelog: (args: import("./command-object").ChangelogOptions) => Promise<import("./changelog").NxReleaseChangelogResult>;
+    releasePublish: (args: import("./command-object").PublishOptions, isCLI?: boolean) => Promise<number>;
+    releaseVersion: (args: import("./command-object").VersionOptions) => Promise<import("./version").NxReleaseVersionResult>;
+    release: (args: import("./command-object").ReleaseOptions) => Promise<import("./version").NxReleaseVersionResult | number>;
+    constructor(overrideReleaseConfig: NxReleaseConfiguration);
+}
 /**
  * @public
  */
-export { releasePublish } from './publish';
+export declare const releaseChangelog: any;
 /**
  * @public
  */
-export { releaseVersion } from './version';
+export declare const releasePublish: any;
 /**
  * @public
  */
-export { release } from './release';
+export declare const releaseVersion: any;
+/**
+ * @public
+ */
+export declare const release: any;

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

@@ -1,23 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.release = exports.releaseVersion = exports.releasePublish = exports.releaseChangelog = void 0;
+exports.release = exports.releaseVersion = exports.releasePublish = exports.releaseChangelog = exports.ReleaseClient = void 0;
+const changelog_1 = require("./changelog");
+const publish_1 = require("./publish");
+const release_1 = require("./release");
+const version_1 = require("./version");
 /**
  * @public
  */
-var changelog_1 = require("./changelog");
-Object.defineProperty(exports, "releaseChangelog", { enumerable: true, get: function () { return changelog_1.releaseChangelog; } });
+class ReleaseClient {
+    constructor(overrideReleaseConfig) {
+        this.overrideReleaseConfig = overrideReleaseConfig;
+        this.releaseChangelog = (0, changelog_1.createAPI)(this.overrideReleaseConfig);
+        this.releasePublish = (0, publish_1.createAPI)(this.overrideReleaseConfig);
+        this.releaseVersion = (0, version_1.createAPI)(this.overrideReleaseConfig);
+        this.release = (0, release_1.createAPI)(this.overrideReleaseConfig);
+    }
+}
+exports.ReleaseClient = ReleaseClient;
+const defaultClient = new ReleaseClient({});
 /**
  * @public
  */
-var publish_1 = require("./publish");
-Object.defineProperty(exports, "releasePublish", { enumerable: true, get: function () { return publish_1.releasePublish; } });
+exports.releaseChangelog = defaultClient.releaseChangelog.bind(defaultClient);
 /**
  * @public
  */
-var version_1 = require("./version");
-Object.defineProperty(exports, "releaseVersion", { enumerable: true, get: function () { return version_1.releaseVersion; } });
+exports.releasePublish = defaultClient.releasePublish.bind(defaultClient);
 /**
  * @public
  */
-var release_1 = require("./release");
-Object.defineProperty(exports, "release", { enumerable: true, get: function () { return release_1.release; } });
+exports.releaseVersion = defaultClient.releaseVersion.bind(defaultClient);
+/**
+ * @public
+ */
+exports.release = defaultClient.release.bind(defaultClient);

package/src/command-line/release/plan.d.ts

@@ -1,3 +1,4 @@
+import { NxReleaseConfiguration } from '../../config/nx-json';
 import { PlanOptions } from './command-object';
 export declare const releasePlanCLIHandler: (args: PlanOptions) => Promise<number>;
-export declare function releasePlan(args: PlanOptions): Promise<string | number>;
+export declare function createAPI(overrideReleaseConfig: NxReleaseConfiguration): (args: PlanOptions) => Promise<string | number>;

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

@@ -1,114 +1,110 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.releasePlanCLIHandler = void 0;
-exports.releasePlan = releasePlan;
+exports.createAPI = createAPI;
 const enquirer_1 = require("enquirer");
 const fs_extra_1 = require("fs-extra");
-const path_1 = require("path");
+const node_path_1 = require("node:path");
 const semver_1 = require("semver");
+const tmp_1 = require("tmp");
 const nx_json_1 = require("../../config/nx-json");
 const file_map_utils_1 = require("../../project-graph/file-map-utils");
 const project_graph_1 = require("../../project-graph/project-graph");
 const output_1 = require("../../utils/output");
 const params_1 = require("../../utils/params");
 const config_1 = require("./config/config");
+const deep_merge_json_1 = require("./config/deep-merge-json");
 const filter_release_groups_1 = require("./config/filter-release-groups");
 const version_plans_1 = require("./config/version-plans");
 const generate_version_plan_content_1 = require("./utils/generate-version-plan-content");
-const git_1 = require("./utils/git");
+const launch_editor_1 = require("./utils/launch-editor");
 const print_changes_1 = require("./utils/print-changes");
-const releasePlanCLIHandler = (args) => (0, params_1.handleErrors)(args.verbose, () => releasePlan(args));
+const print_config_1 = require("./utils/print-config");
+const releasePlanCLIHandler = (args) => (0, params_1.handleErrors)(args.verbose, () => createAPI({})(args));
 exports.releasePlanCLIHandler = releasePlanCLIHandler;
-async function releasePlan(args) {
-    const projectGraph = await (0, project_graph_1.createProjectGraphAsync)({ exitOnError: true });
-    const nxJson = (0, nx_json_1.readNxJson)();
-    if (args.verbose) {
-        process.env.NX_VERBOSE_LOGGING = 'true';
-    }
-    // Apply default configuration to any optional user configuration
-    const { error: configError, nxReleaseConfig } = await (0, config_1.createNxReleaseConfig)(projectGraph, await (0, file_map_utils_1.createProjectFileMapUsingProjectGraph)(projectGraph), nxJson.release);
-    if (configError) {
-        return await (0, config_1.handleNxReleaseConfigError)(configError);
-    }
-    const { error: filterError, releaseGroups, releaseGroupToFilteredProjects, } = (0, filter_release_groups_1.filterReleaseGroups)(projectGraph, nxReleaseConfig, args.projects, args.groups);
-    if (filterError) {
-        output_1.output.error(filterError);
-        process.exit(1);
-    }
-    const versionPlanBumps = {};
-    const setBumpIfNotNone = (projectOrGroup, version) => {
-        if (version !== 'none') {
-            versionPlanBumps[projectOrGroup] = version;
+function createAPI(overrideReleaseConfig) {
+    return async function releasePlan(args) {
+        const projectGraph = await (0, project_graph_1.createProjectGraphAsync)({ exitOnError: true });
+        const nxJson = (0, nx_json_1.readNxJson)();
+        const userProvidedReleaseConfig = (0, deep_merge_json_1.deepMergeJson)(nxJson.release ?? {}, overrideReleaseConfig ?? {});
+        if (args.verbose) {
+            process.env.NX_VERBOSE_LOGGING = 'true';
         }
-    };
-    if (args.message) {
-        const message = (0, git_1.parseConventionalCommitsMessage)(args.message);
-        if (!message) {
-            output_1.output.error({
-                title: 'Changelog message is not in conventional commits format.',
-                bodyLines: [
-                    'Please ensure your message is in the form of:',
-                    '  type(optional scope): description',
-                    '',
-                    'For example:',
-                    '  feat(pkg-b): add new feature',
-                    '  fix(pkg-a): correct a bug',
-                    '  chore: update build process',
-                    '  fix(core)!: breaking change in core package',
-                ],
+        // Apply default configuration to any optional user configuration
+        const { error: configError, nxReleaseConfig } = await (0, config_1.createNxReleaseConfig)(projectGraph, await (0, file_map_utils_1.createProjectFileMapUsingProjectGraph)(projectGraph), nxJson.release);
+        if (configError) {
+            return await (0, config_1.handleNxReleaseConfigError)(configError);
+        }
+        // --print-config exits directly as it is not designed to be combined with any other programmatic operations
+        if (args.printConfig) {
+            return (0, print_config_1.printConfigAndExit)({
+                userProvidedReleaseConfig,
+                nxReleaseConfig,
+                isDebug: args.printConfig === 'debug',
             });
+        }
+        const { error: filterError, releaseGroups, releaseGroupToFilteredProjects, } = (0, filter_release_groups_1.filterReleaseGroups)(projectGraph, nxReleaseConfig, args.projects, args.groups);
+        if (filterError) {
+            output_1.output.error(filterError);
             process.exit(1);
         }
-    }
-    if (releaseGroups[0].name === config_1.IMPLICIT_DEFAULT_RELEASE_GROUP) {
-        const group = releaseGroups[0];
-        if (group.projectsRelationship === 'independent') {
-            for (const project of group.projects) {
-                setBumpIfNotNone(project, args.bump ||
-                    (await promptForVersion(`How do you want to bump the version of the project "${project}"?`)));
+        const versionPlanBumps = {};
+        const setBumpIfNotNone = (projectOrGroup, version) => {
+            if (version !== 'none') {
+                versionPlanBumps[projectOrGroup] = version;
             }
-        }
-        else {
-            // TODO: use project names instead of the implicit default release group name? (though this might be confusing, as users might think they can just delete one of the project bumps to change the behavior to independent versioning)
-            setBumpIfNotNone(group.name, args.bump ||
-                (await promptForVersion(`How do you want to bump the versions of all projects?`)));
-        }
-    }
-    else {
-        for (const group of releaseGroups) {
+        };
+        if (releaseGroups[0].name === config_1.IMPLICIT_DEFAULT_RELEASE_GROUP) {
+            const group = releaseGroups[0];
             if (group.projectsRelationship === 'independent') {
-                for (const project of releaseGroupToFilteredProjects.get(group)) {
+                for (const project of group.projects) {
                     setBumpIfNotNone(project, args.bump ||
-                        (await promptForVersion(`How do you want to bump the version of the project "${project}" within group "${group.name}"?`)));
+                        (await promptForVersion(`How do you want to bump the version of the project "${project}"?`)));
                 }
             }
             else {
+                // TODO: use project names instead of the implicit default release group name? (though this might be confusing, as users might think they can just delete one of the project bumps to change the behavior to independent versioning)
                 setBumpIfNotNone(group.name, args.bump ||
-                    (await promptForVersion(`How do you want to bump the versions of the projects in the group "${group.name}"?`)));
+                    (await promptForVersion(`How do you want to bump the versions of all projects?`)));
             }
         }
-    }
-    if (!Object.keys(versionPlanBumps).length) {
-        output_1.output.warn({
-            title: 'No version bumps were selected so no version plan file was created.',
-        });
+        else {
+            for (const group of releaseGroups) {
+                if (group.projectsRelationship === 'independent') {
+                    for (const project of releaseGroupToFilteredProjects.get(group)) {
+                        setBumpIfNotNone(project, args.bump ||
+                            (await promptForVersion(`How do you want to bump the version of the project "${project}" within group "${group.name}"?`)));
+                    }
+                }
+                else {
+                    setBumpIfNotNone(group.name, args.bump ||
+                        (await promptForVersion(`How do you want to bump the versions of the projects in the group "${group.name}"?`)));
+                }
+            }
+        }
+        if (!Object.keys(versionPlanBumps).length) {
+            output_1.output.warn({
+                title: 'No version bumps were selected so no version plan file was created.',
+            });
+            return 0;
+        }
+        const versionPlanName = `version-plan-${new Date().getTime()}`;
+        const versionPlanMessage = args.message || (await promptForMessage(versionPlanName));
+        const versionPlanFileContent = (0, generate_version_plan_content_1.generateVersionPlanContent)(versionPlanBumps, versionPlanMessage);
+        const versionPlanFileName = `${versionPlanName}.md`;
+        if (args.dryRun) {
+            output_1.output.logSingleLine(`Would create version plan file "${versionPlanFileName}", but --dry-run was set.`);
+            (0, print_changes_1.printDiff)('', versionPlanFileContent, 1);
+        }
+        else {
+            output_1.output.logSingleLine(`Creating version plan file "${versionPlanFileName}"`);
+            (0, print_changes_1.printDiff)('', versionPlanFileContent, 1);
+            const versionPlansAbsolutePath = (0, version_plans_1.getVersionPlansAbsolutePath)();
+            await (0, fs_extra_1.ensureDir)(versionPlansAbsolutePath);
+            await (0, fs_extra_1.writeFile)((0, node_path_1.join)(versionPlansAbsolutePath, versionPlanFileName), versionPlanFileContent);
+        }
         return 0;
-    }
-    const versionPlanMessage = args.message || (await promptForMessage());
-    const versionPlanFileContent = (0, generate_version_plan_content_1.generateVersionPlanContent)(versionPlanBumps, versionPlanMessage);
-    const versionPlanFileName = `version-plan-${new Date().getTime()}.md`;
-    if (args.dryRun) {
-        output_1.output.logSingleLine(`Would create version plan file "${versionPlanFileName}", but --dry-run was set.`);
-        (0, print_changes_1.printDiff)('', versionPlanFileContent, 1);
-    }
-    else {
-        output_1.output.logSingleLine(`Creating version plan file "${versionPlanFileName}"`);
-        (0, print_changes_1.printDiff)('', versionPlanFileContent, 1);
-        const versionPlansAbsolutePath = (0, version_plans_1.getVersionPlansAbsolutePath)();
-        await (0, fs_extra_1.ensureDir)(versionPlansAbsolutePath);
-        await (0, fs_extra_1.writeFile)((0, path_1.join)(versionPlansAbsolutePath, versionPlanFileName), versionPlanFileContent);
-    }
-    return 0;
+    };
 }
 async function promptForVersion(message) {
     try {
@@ -129,41 +125,38 @@ async function promptForVersion(message) {
         process.exit(0);
     }
 }
-async function promptForMessage() {
+async function promptForMessage(versionPlanName) {
     let message;
     do {
-        message = await _promptForMessage();
+        message = await _promptForMessage(versionPlanName);
     } while (!message);
     return message;
 }
-// TODO: support non-conventional commits messages (will require significant changelog renderer changes)
-async function _promptForMessage() {
+async function _promptForMessage(versionPlanName) {
     try {
         const reply = await (0, enquirer_1.prompt)([
             {
                 name: 'message',
-                message: 'What changelog message would you like associated with this change?',
+                message: 'What changelog message would you like associated with this change? (Leave blank to open an external editor for multi-line messages/easier editing)',
                 type: 'input',
             },
         ]);
-        const conventionalCommitsMessage = (0, git_1.parseConventionalCommitsMessage)(reply.message);
-        if (!conventionalCommitsMessage) {
+        let message = reply.message.trim();
+        if (!message.length) {
+            const tmpDir = (0, tmp_1.dirSync)().name;
+            const messageFilePath = (0, node_path_1.join)(tmpDir, `DRAFT_MESSAGE__${versionPlanName}.md`);
+            (0, fs_extra_1.writeFileSync)(messageFilePath, '');
+            await (0, launch_editor_1.launchEditor)(messageFilePath);
+            message = (0, fs_extra_1.readFileSync)(messageFilePath, 'utf-8');
+        }
+        message = message.trim();
+        if (!message) {
             output_1.output.warn({
-                title: 'Changelog message is not in conventional commits format.',
-                bodyLines: [
-                    'Please ensure your message is in the form of:',
-                    '  type(optional scope): description',
-                    '',
-                    'For example:',
-                    '  feat(pkg-b): add new feature',
-                    '  fix(pkg-a): correct a bug',
-                    '  chore: update build process',
-                    '  fix(core)!: breaking change in core package',
-                ],
+                title: 'A changelog message is required in order to create the version plan file',
+                bodyLines: [],
             });
-            return null;
         }
-        return reply.message;
+        return message;
     }
     catch (e) {
         output_1.output.log({

package/src/command-line/release/publish.d.ts

@@ -1,8 +1,4 @@
+import { NxReleaseConfiguration } from '../../config/nx-json';
 import { PublishOptions } from './command-object';
 export declare const releasePublishCLIHandler: (args: PublishOptions) => Promise<number>;
-/**
- * NOTE: This function is also exported for programmatic usage and forms part of the public API
- * of Nx. We intentionally do not wrap the implementation with handleErrors because users need
- * to have control over their own error handling when using the API.
- */
-export declare function releasePublish(args: PublishOptions, isCLI?: boolean): Promise<number>;
+export declare function createAPI(overrideReleaseConfig: NxReleaseConfiguration): (args: PublishOptions, isCLI?: boolean) => Promise<number>;

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.releasePublishCLIHandler = void 0;
-exports.releasePublish = releasePublish;
+exports.createAPI = createAPI;
 const nx_json_1 = require("../../config/nx-json");
 const file_map_utils_1 = require("../../project-graph/file-map-utils");
 const project_graph_1 = require("../../project-graph/project-graph");
@@ -12,52 +12,78 @@ const params_1 = require("../../utils/params");
 const project_graph_utils_1 = require("../../utils/project-graph-utils");
 const graph_1 = require("../graph/graph");
 const config_1 = require("./config/config");
+const deep_merge_json_1 = require("./config/deep-merge-json");
 const filter_release_groups_1 = require("./config/filter-release-groups");
-const releasePublishCLIHandler = (args) => (0, params_1.handleErrors)(args.verbose, () => releasePublish(args, true));
+const print_config_1 = require("./utils/print-config");
+const releasePublishCLIHandler = (args) => (0, params_1.handleErrors)(args.verbose, () => createAPI({})(args, true));
 exports.releasePublishCLIHandler = releasePublishCLIHandler;
-/**
- * NOTE: This function is also exported for programmatic usage and forms part of the public API
- * of Nx. We intentionally do not wrap the implementation with handleErrors because users need
- * to have control over their own error handling when using the API.
- */
-async function releasePublish(args, isCLI = false) {
+function createAPI(overrideReleaseConfig) {
     /**
-     * When used via the CLI, the args object will contain a __overrides_unparsed__ property that is
-     * important for invoking the relevant executor behind the scenes.
-     *
-     * We intentionally do not include that in the function signature, however, so as not to cause
-     * confusing errors for programmatic consumers of this function.
+     * NOTE: This function is also exported for programmatic usage and forms part of the public API
+     * of Nx. We intentionally do not wrap the implementation with handleErrors because users need
+     * to have control over their own error handling when using the API.
      */
-    const _args = args;
-    const projectGraph = await (0, project_graph_1.createProjectGraphAsync)({ exitOnError: true });
-    const nxJson = (0, nx_json_1.readNxJson)();
-    if (_args.verbose) {
-        process.env.NX_VERBOSE_LOGGING = 'true';
-    }
-    // Apply default configuration to any optional user configuration
-    const { error: configError, nxReleaseConfig } = await (0, config_1.createNxReleaseConfig)(projectGraph, await (0, file_map_utils_1.createProjectFileMapUsingProjectGraph)(projectGraph), nxJson.release);
-    if (configError) {
-        return await (0, config_1.handleNxReleaseConfigError)(configError);
-    }
-    const { error: filterError, releaseGroups, releaseGroupToFilteredProjects, } = (0, filter_release_groups_1.filterReleaseGroups)(projectGraph, nxReleaseConfig, _args.projects, _args.groups);
-    if (filterError) {
-        output_1.output.error(filterError);
-        process.exit(1);
-    }
-    /**
-     * If the user is filtering to a subset of projects or groups, we should not run the publish task
-     * for dependencies, because that could cause projects outset of the filtered set to be published.
-     */
-    const shouldExcludeTaskDependencies = _args.projects?.length > 0 ||
-        _args.groups?.length > 0 ||
-        args.excludeTaskDependencies;
-    let overallExitStatus = 0;
-    if (args.projects?.length) {
+    return async function releasePublish(args, isCLI = false) {
+        /**
+         * When used via the CLI, the args object will contain a __overrides_unparsed__ property that is
+         * important for invoking the relevant executor behind the scenes.
+         *
+         * We intentionally do not include that in the function signature, however, so as not to cause
+         * confusing errors for programmatic consumers of this function.
+         */
+        const _args = args;
+        const projectGraph = await (0, project_graph_1.createProjectGraphAsync)({ exitOnError: true });
+        const nxJson = (0, nx_json_1.readNxJson)();
+        const userProvidedReleaseConfig = (0, deep_merge_json_1.deepMergeJson)(nxJson.release ?? {}, overrideReleaseConfig ?? {});
+        if (_args.verbose) {
+            process.env.NX_VERBOSE_LOGGING = 'true';
+        }
+        // Apply default configuration to any optional user configuration
+        const { error: configError, nxReleaseConfig } = await (0, config_1.createNxReleaseConfig)(projectGraph, await (0, file_map_utils_1.createProjectFileMapUsingProjectGraph)(projectGraph), userProvidedReleaseConfig);
+        if (configError) {
+            return await (0, config_1.handleNxReleaseConfigError)(configError);
+        }
+        // --print-config exits directly as it is not designed to be combined with any other programmatic operations
+        if (args.printConfig) {
+            return (0, print_config_1.printConfigAndExit)({
+                userProvidedReleaseConfig,
+                nxReleaseConfig,
+                isDebug: args.printConfig === 'debug',
+            });
+        }
+        const { error: filterError, releaseGroups, releaseGroupToFilteredProjects, } = (0, filter_release_groups_1.filterReleaseGroups)(projectGraph, nxReleaseConfig, _args.projects, _args.groups);
+        if (filterError) {
+            output_1.output.error(filterError);
+            process.exit(1);
+        }
+        /**
+         * If the user is filtering to a subset of projects or groups, we should not run the publish task
+         * for dependencies, because that could cause projects outset of the filtered set to be published.
+         */
+        const shouldExcludeTaskDependencies = _args.projects?.length > 0 ||
+            _args.groups?.length > 0 ||
+            args.excludeTaskDependencies;
+        let overallExitStatus = 0;
+        if (args.projects?.length) {
+            /**
+             * Run publishing for all remaining release groups and filtered projects within them
+             */
+            for (const releaseGroup of releaseGroups) {
+                const status = await runPublishOnProjects(_args, projectGraph, nxJson, Array.from(releaseGroupToFilteredProjects.get(releaseGroup)), isCLI, {
+                    excludeTaskDependencies: shouldExcludeTaskDependencies,
+                    loadDotEnvFiles: process.env.NX_LOAD_DOT_ENV_FILES !== 'false',
+                });
+                if (status !== 0) {
+                    overallExitStatus = status || 1;
+                }
+            }
+            return overallExitStatus;
+        }
         /**
-         * Run publishing for all remaining release groups and filtered projects within them
+         * Run publishing for all remaining release groups
          */
         for (const releaseGroup of releaseGroups) {
-            const status = await runPublishOnProjects(_args, projectGraph, nxJson, Array.from(releaseGroupToFilteredProjects.get(releaseGroup)), isCLI, {
+            const status = await runPublishOnProjects(_args, projectGraph, nxJson, releaseGroup.projects, isCLI, {
                 excludeTaskDependencies: shouldExcludeTaskDependencies,
                 loadDotEnvFiles: process.env.NX_LOAD_DOT_ENV_FILES !== 'false',
             });
@@ -66,20 +92,7 @@ async function releasePublish(args, isCLI = false) {
             }
         }
         return overallExitStatus;
-    }
-    /**
-     * Run publishing for all remaining release groups
-     */
-    for (const releaseGroup of releaseGroups) {
-        const status = await runPublishOnProjects(_args, projectGraph, nxJson, releaseGroup.projects, isCLI, {
-            excludeTaskDependencies: shouldExcludeTaskDependencies,
-            loadDotEnvFiles: process.env.NX_LOAD_DOT_ENV_FILES !== 'false',
-        });
-        if (status !== 0) {
-            overallExitStatus = status || 1;
-        }
-    }
-    return overallExitStatus;
+    };
 }
 async function runPublishOnProjects(args, projectGraph, nxJson, projectNames, isCLI, extraOptions) {
     const projectsToRun = projectNames.map((projectName) => projectGraph.nodes[projectName]);

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

@@ -1,4 +1,5 @@
+import { NxReleaseConfiguration } from '../../config/nx-json';
 import { ReleaseOptions, VersionOptions } from './command-object';
 import { NxReleaseVersionResult } from './version';
 export declare const releaseCLIHandler: (args: VersionOptions) => Promise<number>;
-export declare function release(args: ReleaseOptions): Promise<NxReleaseVersionResult | number>;
+export declare function createAPI(overrideReleaseConfig: NxReleaseConfiguration): (args: ReleaseOptions) => Promise<NxReleaseVersionResult | number>;