feat(release): add nx release plan:check command to ensure relevant version plans exist (#27343)

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

When using version plans as a versioning strategy with `nx release`,
there is no way to enforce that version plan files are created when
changing files.

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

There is a new `nx release plan:check` subcommand, intended to be run in
CI (and/or potentially a git hook) which will return with exit code 1 if
touched projects are not represented in at least one version plan file
on disk.

What constitutes a touched file is shared with our `affected` logic in
other commands, with the additionally capability to be able to ignore
file patterns from consideration. This would be useful for not requiring
version plans when only documentation or spec files change, for example.

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #

Author: JamesHenry

e2e/release/src/version-plans-check.test.ts

@@ -463,7 +463,8 @@ To fix this you will either need to add a package.json file at that location, or
 
             if (options.releaseGroup.projectsRelationship === 'independent') {
               specifier = (
-                options.releaseGroup.versionPlans as ProjectsVersionPlan[]
+                options.releaseGroup
+                  .resolvedVersionPlans as ProjectsVersionPlan[]
               ).reduce((spec: ReleaseType, plan: ProjectsVersionPlan) => {
                 if (!spec) {
                   return plan.projectVersionBumps[projectName];
@@ -482,7 +483,7 @@ To fix this you will either need to add a package.json file at that location, or
               }, null);
             } else {
               specifier = (
-                options.releaseGroup.versionPlans as GroupVersionPlan[]
+                options.releaseGroup.resolvedVersionPlans as GroupVersionPlan[]
               ).reduce((spec: ReleaseType, plan: GroupVersionPlan) => {
                 if (!spec) {
                   return plan.groupVersionBump;
@@ -522,7 +523,7 @@ To fix this you will either need to add a package.json file at that location, or
             }
 
             if (options.deleteVersionPlans) {
-              options.releaseGroup.versionPlans.forEach((p) => {
+              (options.releaseGroup.resolvedVersionPlans || []).forEach((p) => {
                 deleteVersionPlanCallbacks.push(async (dryRun?: boolean) => {
                   if (!dryRun) {
                     await remove(p.absolutePath);
@@ -599,14 +600,14 @@ To fix this you will either need to add a package.json file at that location, or
 
         // For version-plans, we don't just need to consider the current batch of projects, but also the ones that are actually being updated as part of the plan file(s)
         if (isInCurrentBatch && options.specifierSource === 'version-plans') {
-          isInCurrentBatch = (options.releaseGroup.versionPlans || []).some(
-            (plan) => {
-              if ('projectVersionBumps' in plan) {
-                return plan.projectVersionBumps[dependentProject.source];
-              }
-              return true;
+          isInCurrentBatch = (
+            options.releaseGroup.resolvedVersionPlans || []
+          ).some((plan) => {
+            if ('projectVersionBumps' in plan) {
+              return plan.projectVersionBumps[dependentProject.source];
             }
-          );
+            return true;
+          });
         }
 
         if (!isInCurrentBatch) {

packages/js/src/generators/release-version/release-version.ts

@@ -186,8 +186,15 @@
                 "type": "string"
               },
               "versionPlans": {
-                "type": "boolean",
-                "description": "Enables using version plans as a specifier source for versioning and to determine changes for changelog generation."
+                "oneOf": [
+                  {
+                    "$ref": "#/definitions/NxReleaseVersionPlansConfiguration"
+                  },
+                  {
+                    "type": "boolean",
+                    "description": "Enables using version plans as a specifier source for versioning and to determine changes for changelog generation."
+                  }
+                ]
               }
             },
             "required": ["projects"]
@@ -239,8 +246,15 @@
           "$ref": "#/definitions/NxReleaseVersionConfiguration"
         },
         "versionPlans": {
-          "type": "boolean",
-          "description": "Enables using version plans as a specifier source for versioning and to determine changes for changelog generation."
+          "oneOf": [
+            {
+              "$ref": "#/definitions/NxReleaseVersionPlansConfiguration"
+            },
+            {
+              "type": "boolean",
+              "description": "Enables using version plans as a specifier source for versioning and to determine changes for changelog generation."
+            }
+          ]
         },
         "releaseTagPattern": {
           "type": "string"
@@ -698,6 +712,18 @@
         }
       }
     },
+    "NxReleaseVersionPlansConfiguration": {
+      "type": "object",
+      "properties": {
+        "ignorePatternsForPlanCheck": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Changes to files matching any of these optional patterns will be excluded from the affected project logic within the `nx release plan:check` command. This is useful for ignoring files that are not relevant to the versioning process, such as documentation or configuration files."
+        }
+      }
+    },
     "ChangelogRenderOptions": {
       "type": "object",
       "additionalProperties": true

packages/nx/schemas/nx-schema.json

@@ -43,7 +43,7 @@ import {
   GroupVersionPlan,
   ProjectsVersionPlan,
   readRawVersionPlans,
-  setVersionPlansOnGroups,
+  setResolvedVersionPlansOnGroups,
 } from './config/version-plans';
 import {
   GitCommit,
@@ -179,7 +179,7 @@ export function createAPI(overrideReleaseConfig: NxReleaseConfiguration) {
       process.exit(1);
     }
     const rawVersionPlans = await readRawVersionPlans();
-    setVersionPlansOnGroups(
+    setResolvedVersionPlansOnGroups(
       rawVersionPlans,
       releaseGroups,
       Object.keys(projectGraph.nodes)
@@ -274,12 +274,13 @@ export function createAPI(overrideReleaseConfig: NxReleaseConfiguration) {
 
     // If there are multiple release groups, we'll just skip the workspace changelog anyway.
     const versionPlansEnabledForWorkspaceChangelog =
-      releaseGroups[0].versionPlans;
+      releaseGroups[0].resolvedVersionPlans;
     if (versionPlansEnabledForWorkspaceChangelog) {
       if (releaseGroups.length === 1) {
         const releaseGroup = releaseGroups[0];
         if (releaseGroup.projectsRelationship === 'fixed') {
-          const versionPlans = releaseGroup.versionPlans as GroupVersionPlan[];
+          const versionPlans =
+            releaseGroup.resolvedVersionPlans as GroupVersionPlan[];
           workspaceChangelogChanges = versionPlans
             .flatMap((vp) => {
               const releaseType = versionPlanSemverReleaseTypeToChangelogType(
@@ -490,8 +491,10 @@ export function createAPI(overrideReleaseConfig: NxReleaseConfiguration) {
           // TODO: remove this after the changelog renderer is refactored to remove coupling with git commits
           let commits: GitCommit[];
 
-          if (releaseGroup.versionPlans) {
-            changes = (releaseGroup.versionPlans as ProjectsVersionPlan[])
+          if (releaseGroup.resolvedVersionPlans) {
+            changes = (
+              releaseGroup.resolvedVersionPlans as ProjectsVersionPlan[]
+            )
               .map((vp) => {
                 const bumpForProject = vp.projectVersionBumps[project.name];
                 if (!bumpForProject) {
@@ -637,8 +640,8 @@ export function createAPI(overrideReleaseConfig: NxReleaseConfiguration) {
         let changes: ChangelogChange[] = [];
         // TODO: remove this after the changelog renderer is refactored to remove coupling with git commits
         let commits: GitCommit[] = [];
-        if (releaseGroup.versionPlans) {
-          changes = (releaseGroup.versionPlans as GroupVersionPlan[])
+        if (releaseGroup.resolvedVersionPlans) {
+          changes = (releaseGroup.resolvedVersionPlans as GroupVersionPlan[])
             .flatMap((vp) => {
               const releaseType = versionPlanSemverReleaseTypeToChangelogType(
                 vp.groupVersionBump
@@ -918,8 +921,8 @@ async function applyChangesAndExit(
   if (args.deleteVersionPlans && !args.dryRun) {
     const planFiles = new Set<string>();
     releaseGroups.forEach((group) => {
-      if (group.versionPlans) {
-        group.versionPlans.forEach((plan) => {
+      if (group.resolvedVersionPlans) {
+        group.resolvedVersionPlans.forEach((plan) => {
           removeSync(plan.absolutePath);
           planFiles.add(plan.relativePath);
         });

packages/nx/src/command-line/release/changelog.ts

@@ -1,23 +1,28 @@
 import { Argv, CommandModule, showHelp } from 'yargs';
 import { readNxJson } from '../../config/nx-json';
+import { readParallelFromArgsAndEnv } from '../../utils/command-line-utils';
 import { logger } from '../../utils/logger';
 import {
   OutputStyle,
   RunManyOptions,
   parseCSV,
+  withAffectedOptions,
   withOutputStyleOption,
   withOverrides,
   withRunManyOptions,
 } from '../yargs-utils/shared-options';
 import { VersionData } from './utils/shared';
-import { readParallelFromArgsAndEnv } from '../../utils/command-line-utils';
 
-export interface NxReleaseArgs {
+// Implemented by every command and subcommand
+export interface BaseNxReleaseArgs {
+  verbose?: boolean;
+  printConfig?: boolean | 'debug';
+}
+
+export interface NxReleaseArgs extends BaseNxReleaseArgs {
   groups?: string[];
   projects?: string[];
   dryRun?: boolean;
-  verbose?: boolean;
-  printConfig?: boolean | 'debug';
 }
 
 interface GitCommitAndTagOptions {
@@ -66,6 +71,14 @@ export type PlanOptions = NxReleaseArgs & {
   message?: string;
 };
 
+export type PlanCheckOptions = BaseNxReleaseArgs & {
+  base?: string;
+  head?: string;
+  files?: string;
+  uncommitted?: boolean;
+  untracked?: boolean;
+};
+
 export type ReleaseOptions = NxReleaseArgs &
   FirstReleaseArgs & {
     yes?: boolean;
@@ -94,6 +107,7 @@ export const yargsReleaseCommand: CommandModule<
       .command(changelogCommand)
       .command(publishCommand)
       .command(planCommand)
+      .command(planCheckCommand)
       .demandCommand()
       // Error on typos/mistyped CLI args, there is no reason to support arbitrary unknown args for these commands
       .strictOptions()
@@ -337,6 +351,7 @@ const publishCommand: CommandModule<NxReleaseArgs, PublishOptions> = {
 const planCommand: CommandModule<NxReleaseArgs, PlanOptions> = {
   command: 'plan [bump]',
   aliases: ['pl'],
+  // TODO: Remove this when docs are added
   // Create a plan to pick a new version and generate a changelog entry.
   // Hidden for now until the feature is more stable
   describe: false,
@@ -371,6 +386,20 @@ const planCommand: CommandModule<NxReleaseArgs, PlanOptions> = {
   },
 };
 
+const planCheckCommand: CommandModule<NxReleaseArgs, PlanCheckOptions> = {
+  command: 'plan:check',
+  // TODO: Remove this when docs are added
+  // Create a plan to pick a new version and generate a changelog entry.
+  // Hidden for now until the feature is more stable
+  describe: false,
+  builder: (yargs) => withAffectedOptions(yargs),
+  handler: async (args) => {
+    const release = await import('./plan-check');
+    const result = await release.releasePlanCheckCLIHandler(args);
+    process.exit(result);
+  },
+};
+
 function coerceParallelOption(args: any) {
   return {
     ...args,