feat(core): deprecate affected:apps and affected:libs (#10524)

Co-authored-by: Victor Savkin <mail@vsavkin.com>

docs/generated/cli/affected-apps.md

@@ -5,6 +5,8 @@ description: 'Print applications affected by changes'
 
 # affected:apps
 
+**Deprecated:** Use `nx print-affected --type=app ...` instead. This command will be removed in v15.
+
 Print applications affected by changes
 
 ## Usage

docs/generated/cli/affected-libs.md

@@ -5,6 +5,8 @@ description: 'Print libraries affected by changes'
 
 # affected:libs
 
+**Deprecated:** Use `nx print-affected --type=lib ...` instead. This command will be removed in v15.
+
 Print libraries affected by changes
 
 ## Usage

docs/generated/cli/print-affected.md

@@ -139,6 +139,14 @@ Default: false
 
 Rerun the tasks even when the results are available in the cache
 
+### type
+
+Type: string
+
+Choices: [app, lib]
+
+Select the type of projects to be returned (e.g., --type=app)
+
 ### uncommitted
 
 Type: boolean

docs/generated/packages/cli.json

@@ -57,19 +57,19 @@
       "name": "affected:apps",
       "id": "affected-apps",
       "file": "generated/cli/affected-apps",
-      "content": "---\ntitle: 'affected:apps - CLI command'\ndescription: 'Print applications affected by changes'\n---\n\n# affected:apps\n\nPrint applications affected by changes\n\n## Usage\n\n```bash\nnx affected:apps\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint the names of all the apps affected by changing the index.ts file:\n\n```bash\nnx affected:apps --files=libs/mylib/src/index.ts\n```\n\nPrint the names of all the apps affected by the changes between main and HEAD (e.g., PR):\n\n```bash\nnx affected:apps --base=main --head=HEAD\n```\n\nPrint the names of all the apps affected by the last commit on main:\n\n```bash\nnx affected:apps --base=main~1 --head=main\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### plain\n\nProduces a plain output for affected:apps and affected:libs\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
+      "content": "---\ntitle: 'affected:apps - CLI command'\ndescription: 'Print applications affected by changes'\n---\n\n# affected:apps\n\n**Deprecated:** Use `nx print-affected --type=app ...` instead. This command will be removed in v15.\n\nPrint applications affected by changes\n\n## Usage\n\n```bash\nnx affected:apps\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint the names of all the apps affected by changing the index.ts file:\n\n```bash\nnx affected:apps --files=libs/mylib/src/index.ts\n```\n\nPrint the names of all the apps affected by the changes between main and HEAD (e.g., PR):\n\n```bash\nnx affected:apps --base=main --head=HEAD\n```\n\nPrint the names of all the apps affected by the last commit on main:\n\n```bash\nnx affected:apps --base=main~1 --head=main\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### plain\n\nProduces a plain output for affected:apps and affected:libs\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
     },
     {
       "name": "affected:libs",
       "id": "affected-libs",
       "file": "generated/cli/affected-libs",
-      "content": "---\ntitle: 'affected:libs - CLI command'\ndescription: 'Print libraries affected by changes'\n---\n\n# affected:libs\n\nPrint libraries affected by changes\n\n## Usage\n\n```bash\nnx affected:libs\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint the names of all the libs affected by changing the index.ts file:\n\n```bash\nnx affected:libs --files=libs/mylib/src/index.ts\n```\n\nPrint the names of all the libs affected by the changes between main and HEAD (e.g., PR):\n\n```bash\nnx affected:libs --base=main --head=HEAD\n```\n\nPrint the names of all the libs affected by the last commit on main:\n\n```bash\nnx affected:libs --base=main~1 --head=main\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### plain\n\nProduces a plain output for affected:apps and affected:libs\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
+      "content": "---\ntitle: 'affected:libs - CLI command'\ndescription: 'Print libraries affected by changes'\n---\n\n# affected:libs\n\n**Deprecated:** Use `nx print-affected --type=lib ...` instead. This command will be removed in v15.\n\nPrint libraries affected by changes\n\n## Usage\n\n```bash\nnx affected:libs\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint the names of all the libs affected by changing the index.ts file:\n\n```bash\nnx affected:libs --files=libs/mylib/src/index.ts\n```\n\nPrint the names of all the libs affected by the changes between main and HEAD (e.g., PR):\n\n```bash\nnx affected:libs --base=main --head=HEAD\n```\n\nPrint the names of all the libs affected by the last commit on main:\n\n```bash\nnx affected:libs --base=main~1 --head=main\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### plain\n\nProduces a plain output for affected:apps and affected:libs\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
     },
     {
       "name": "print-affected",
       "id": "print-affected",
       "file": "generated/cli/print-affected",
-      "content": "---\ntitle: 'print-affected - CLI command'\ndescription: 'Prints information about the projects and targets affected by changes'\n---\n\n# print-affected\n\nPrints information about the projects and targets affected by changes\n\n## Usage\n\n```bash\nnx print-affected\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint information about affected projects and the project graph:\n\n```bash\nnx print-affected\n```\n\nPrint information about the projects affected by the changes between main and HEAD (e.g,. PR):\n\n```bash\nnx print-affected --base=main --head=HEAD\n```\n\nPrints information about the affected projects and a list of tasks to test them:\n\n```bash\nnx print-affected --target=test\n```\n\nPrints the projects property from the print-affected output:\n\n```bash\nnx print-affected --target=build --select=projects\n```\n\nPrints the tasks.target.project property from the print-affected output:\n\n```bash\nnx print-affected --target=build --select=tasks.target.project\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### select\n\nType: string\n\nSelect the subset of the returned json document (e.g., --selected=projects)\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
+      "content": "---\ntitle: 'print-affected - CLI command'\ndescription: 'Prints information about the projects and targets affected by changes'\n---\n\n# print-affected\n\nPrints information about the projects and targets affected by changes\n\n## Usage\n\n```bash\nnx print-affected\n```\n\n[Install `nx` globally](/getting-started/nx-setup#install-nx) to invoke the command directly using `nx`, or use `npx nx`, `yarn nx`, or `pnpx nx`.\n\n### Examples\n\nPrint information about affected projects and the project graph:\n\n```bash\nnx print-affected\n```\n\nPrint information about the projects affected by the changes between main and HEAD (e.g,. PR):\n\n```bash\nnx print-affected --base=main --head=HEAD\n```\n\nPrints information about the affected projects and a list of tasks to test them:\n\n```bash\nnx print-affected --target=test\n```\n\nPrints the projects property from the print-affected output:\n\n```bash\nnx print-affected --target=build --select=projects\n```\n\nPrints the tasks.target.project property from the print-affected output:\n\n```bash\nnx print-affected --target=build --select=tasks.target.project\n```\n\n## Options\n\n### all\n\nType: boolean\n\nAll projects\n\n### base\n\nType: string\n\nBase of the current branch (usually main)\n\n### configuration\n\nType: string\n\nThis is the configuration to use when performing tasks on projects\n\n### exclude\n\nType: array\n\nDefault: []\n\nExclude certain projects from being processed\n\n### files\n\nType: array\n\nChange the way Nx is calculating the affected command by providing directly changed files, list of files delimited by commas\n\n### head\n\nType: string\n\nLatest commit of the current branch (usually HEAD)\n\n### help\n\nType: boolean\n\nShow help\n\n### nx-bail\n\nType: boolean\n\nDefault: false\n\nStop command execution after the first failed task\n\n### nx-ignore-cycles\n\nType: boolean\n\nDefault: false\n\nIgnore cycles in the task graph\n\n### ~~only-failed~~\n\nType: boolean\n\nDefault: false\n\n**Deprecated:** The command to rerun failed projects will appear if projects fail. This now does nothing and will be removed in v15.\n\nIsolate projects which previously failed\n\n### runner\n\nType: string\n\nThis is the name of the tasks runner configured in nx.json\n\n### select\n\nType: string\n\nSelect the subset of the returned json document (e.g., --selected=projects)\n\n### skip-nx-cache\n\nType: boolean\n\nDefault: false\n\nRerun the tasks even when the results are available in the cache\n\n### type\n\nType: string\n\nChoices: [app, lib]\n\nSelect the type of projects to be returned (e.g., --type=app)\n\n### uncommitted\n\nType: boolean\n\nUncommitted changes\n\n### untracked\n\nType: boolean\n\nUntracked changes\n\n### verbose\n\nPrint additional error stack trace on failure\n\n### version\n\nType: boolean\n\nShow version number\n"
     },
     {
       "name": "format:check",

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

@@ -47,6 +47,10 @@ export async function affected(
           console.log(apps.join(' '));
         } else {
           if (apps.length) {
+            output.warn({
+              title:
+                'Deprecated: Use "nx print-affected --type=app --select=projects" instead. This command will be removed in v15.',
+            });
             output.log({
               title: 'Affected apps:',
               bodyLines: apps.map((app) => `${output.dim('-')} ${app}`),
@@ -63,6 +67,10 @@ export async function affected(
           console.log(libs.join(' '));
         } else {
           if (libs.length) {
+            output.warn({
+              title:
+                'Deprecated: Use "nx print-affected --type=lib --select=projects" instead. This command will be removed in v15.',
+            });
             output.log({
               title: 'Affected libs:',
               bodyLines: libs.map((lib) => `${output.dim('-')} ${lib}`),

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

@@ -148,7 +148,9 @@ ${daemonHelpOutput}
   })
   .command({
     command: 'affected:apps',
-    describe: 'Print applications affected by changes',
+    deprecated:
+      'Use `nx print-affected --type=app ...` instead. This command will be removed in v15.',
+    describe: `Print applications affected by changes`,
     builder: (yargs) =>
       linkToNxDevAndExamples(
         withAffectedOptions(withPlainOption(yargs)),
@@ -159,7 +161,9 @@ ${daemonHelpOutput}
   })
   .command({
     command: 'affected:libs',
-    describe: 'Print libraries affected by changes',
+    deprecated:
+      'Use `nx print-affected --type=lib ...` instead. This command will be removed in v15.',
+    describe: `Print libraries affected by changes`,
     builder: (yargs) =>
       linkToNxDevAndExamples(
         withAffectedOptions(withPlainOption(yargs)),
@@ -336,11 +340,17 @@ function withDaemonStartOptions(yargs: yargs.Argv): yargs.Argv {
 }
 
 function withPrintAffectedOptions(yargs: yargs.Argv): yargs.Argv {
-  return yargs.option('select', {
-    type: 'string',
-    describe:
-      'Select the subset of the returned json document (e.g., --selected=projects)',
-  });
+  return yargs
+    .option('select', {
+      type: 'string',
+      describe:
+        'Select the subset of the returned json document (e.g., --selected=projects)',
+    })
+    .option('type', {
+      type: 'string',
+      choices: ['app', 'lib'],
+      describe: 'Select the type of projects to be returned (e.g., --type=app)',
+    });
 }
 
 function withPlainOption(yargs: yargs.Argv): yargs.Argv {

packages/nx/src/command-line/print-affected.ts

@@ -14,9 +14,13 @@ export async function printAffected(
   nxArgs: NxArgs,
   overrides: yargs.Arguments
 ) {
-  const projectNames = affectedProjects.map((p) => p.name);
+  const projectNames = affectedProjects
+    .filter((p) => (nxArgs.type ? p.type === nxArgs.type : true))
+    .map((p) => p.name);
   const tasksJson = await createTasks(
-    affectedProjectsWithTargetAndConfig,
+    affectedProjectsWithTargetAndConfig.filter((p) =>
+      nxArgs.type ? p.type === nxArgs.type : true
+    ),
     projectGraph,
     nxArgs,
     overrides

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

@@ -98,6 +98,7 @@ const runAffected: string[] = [
   'files',
   'plain',
   'select',
+  'type',
 ];
 
 export interface RawNxArgs extends NxArgs {
@@ -129,6 +130,7 @@ export interface NxArgs {
   scan?: boolean;
   nxBail?: boolean;
   nxIgnoreCycles?: boolean;
+  type?: string;
 }
 
 const ignoreArgs = ['$0', '_'];

scripts/documentation/generate-cli-data.ts

@@ -9,7 +9,6 @@ import {
   getCommands,
   parseCommand,
   ParsedCommand,
-  sortAlphabeticallyFunction,
 } from './utils';
 import { register as registerTsConfigPaths } from 'tsconfig-paths';
 import { examples } from '../../packages/nx/src/command-line/examples';
@@ -48,7 +47,7 @@ description: "${command.description}"
 ---
 # ${command.name}
 
-${command.description}
+${dedent`${formatDeprecated(command.description, command.deprecated)}`}
 
 ## Usage