feat(core): support collecting migrations skipping the already applie…

…d ones

docs/generated/cli/migrate.md

@@ -35,7 +35,7 @@ Update @nrwl/workspace to "9.0.0". This will update other packages and will gene
  nx migrate 9.0.0
 ```
 
-Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what installed locally:
+Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what is installed locally:
 
 ```shell
  nx migrate @nrwl/workspace@9.0.0 --from="@nrwl/workspace@8.0.0,@nrwl/node@8.0.0"
@@ -59,6 +59,12 @@ Collect package updates and migrations in interactive mode. In this mode, the us
  nx migrate latest --interactive
 ```
 
+Collect package updates and migrations starting with version 14.5.0 of "nx" (and Nx first-party plugins), regardless of what is installed locally, while skipping migrations that were meant to be applied on previous updates:
+
+```shell
+ nx migrate latest --from=nx@14.5.0 --skip-applied-migrations
+```
+
 Run migrations from the provided migrations.json file. You can modify migrations.json and run this command many times:
 
 ```shell
@@ -121,6 +127,14 @@ Type: `string`
 
 Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json)
 
+### skipAppliedMigrations
+
+Type: `boolean`
+
+Default: `false`
+
+Skip collecting migrations that were meant to be applied on previous updates. To be used with --from
+
 ### to
 
 Type: `string`

docs/generated/packages/nx/documents/migrate.md

@@ -35,7 +35,7 @@ Update @nrwl/workspace to "9.0.0". This will update other packages and will gene
  nx migrate 9.0.0
 ```
 
-Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what installed locally:
+Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what is installed locally:
 
 ```shell
  nx migrate @nrwl/workspace@9.0.0 --from="@nrwl/workspace@8.0.0,@nrwl/node@8.0.0"
@@ -59,6 +59,12 @@ Collect package updates and migrations in interactive mode. In this mode, the us
  nx migrate latest --interactive
 ```
 
+Collect package updates and migrations starting with version 14.5.0 of "nx" (and Nx first-party plugins), regardless of what is installed locally, while skipping migrations that were meant to be applied on previous updates:
+
+```shell
+ nx migrate latest --from=nx@14.5.0 --skip-applied-migrations
+```
+
 Run migrations from the provided migrations.json file. You can modify migrations.json and run this command many times:
 
 ```shell
@@ -121,6 +127,14 @@ Type: `string`
 
 Execute migrations from a file (when the file isn't provided, execute migrations from migrations.json)
 
+### skipAppliedMigrations
+
+Type: `boolean`
+
+Default: `false`
+
+Skip collecting migrations that were meant to be applied on previous updates. To be used with --from
+
 ### to
 
 Type: `string`

packages/nx/src/command-line/examples.ts

@@ -330,7 +330,7 @@ export const examples: Record<string, Example[]> = {
       command:
         'migrate @nrwl/workspace@9.0.0 --from="@nrwl/workspace@8.0.0,@nrwl/node@8.0.0"',
       description:
-        'Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what installed locally',
+        'Update @nrwl/workspace and generate the list of migrations starting with version 8.0.0 of @nrwl/workspace and @nrwl/node, regardless of what is installed locally',
     },
     {
       command:
@@ -348,6 +348,11 @@ export const examples: Record<string, Example[]> = {
       description:
         'Collect package updates and migrations in interactive mode. In this mode, the user will be prompted whether to apply any optional package update and migration',
     },
+    {
+      command: 'migrate latest --from=nx@14.5.0 --skip-applied-migrations',
+      description:
+        'Collect package updates and migrations starting with version 14.5.0 of "nx" (and Nx first-party plugins), regardless of what is installed locally, while skipping migrations that were meant to be applied on previous updates',
+    },
     {
       command: 'migrate --run-migrations=migrations.json',
       description:

packages/nx/src/command-line/migrate.spec.ts

@@ -1365,6 +1365,112 @@ describe('Migration', () => {
         },
       });
     });
+
+    it('should generate the correct migrations when  "--only-skipped-migrations"', async () => {
+      const migrator = new Migrator({
+        packageJson: createPackageJson({
+          dependencies: {
+            parent: '1.0.0',
+            pkg1: '1.0.0',
+          },
+        }),
+        getInstalledPackageVersion: (p, overrides) => overrides?.[p] ?? '1.0.0',
+        fetch: (p) => {
+          if (p === 'parent') {
+            return Promise.resolve({
+              version: '2.0.0',
+              packageGroup: [{ package: 'pkg1', version: '*' }],
+              generators: {
+                // previous migration
+                migration1: {
+                  version: '1.0.0',
+                  description: 'migration1 desc',
+                  requires: {
+                    // didn't meet requirements and now meets requirements, should collect it
+                    pkg1: '>=2.0.0',
+                  },
+                },
+                // previous migration
+                migration2: {
+                  version: '1.0.0',
+                  description: 'migration2 desc',
+                  requires: {
+                    // didn't meet requirements and now doesn't meet requirements, should not collect it
+                    pkg1: '>=3.0.0',
+                  },
+                },
+                // previous migration, no requirements, should not collect it
+                migration3: {
+                  version: '1.0.0',
+                  description: 'migration3 desc',
+                },
+                // new migration
+                migration4: {
+                  version: '2.0.0',
+                  description: 'migration4 desc',
+                  requires: {
+                    // meets requirements, should collect it
+                    pkg1: '>=2.0.0',
+                  },
+                },
+                // new migration
+                migration5: {
+                  version: '2.0.0',
+                  description: 'migration5 desc',
+                  requires: {
+                    // doesn't meet requirements, should not collect it
+                    pkg1: '>=3.0.0',
+                  },
+                },
+                // new migrationg, no requirements, should collect it
+                migration6: {
+                  version: '2.0.0',
+                  description: 'migration6 desc',
+                },
+              },
+            });
+          } else if (p === 'pkg1') {
+            return Promise.resolve({ version: '2.0.0' });
+          } else {
+            return Promise.resolve(null);
+          }
+        },
+        from: { parent: '0.1.0' },
+        to: {},
+        skipAppliedMigrations: true,
+      });
+
+      const result = await migrator.updatePackageJson('parent', '2.0.0');
+
+      expect(result).toEqual({
+        migrations: [
+          {
+            version: '1.0.0',
+            name: 'migration1',
+            package: 'parent',
+            description: 'migration1 desc',
+            requires: { pkg1: '>=2.0.0' },
+          },
+          {
+            version: '2.0.0',
+            name: 'migration4',
+            package: 'parent',
+            description: 'migration4 desc',
+            requires: { pkg1: '>=2.0.0' },
+          },
+          {
+            version: '2.0.0',
+            name: 'migration6',
+            package: 'parent',
+            description: 'migration6 desc',
+          },
+        ],
+        packageJson: {
+          parent: { version: '2.0.0', addToPackageJson: false },
+          pkg1: { version: '2.0.0', addToPackageJson: false },
+        },
+      });
+    });
   });
 
   describe('normalizeVersions', () => {