feat(cli): cdk watch --concurrency (#21598)

This PR adds #20345's `--concurrency` to `cdk watch` mode. Given that `cdk watch` is a wrapper around `deploy`, this is a simple matter of passing the `concurrency` option along.

Fixes #21597

----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/aws-cdk/README.md

@@ -458,6 +458,15 @@ locally to your terminal. To disable this feature you can pass the `--no-logs` o
 $ cdk watch --no-logs
 ```
 
+You can increase the concurrency by which `watch` will deploy and hotswap
+your stacks by specifying `--concurrency N`. `--concurrency` for `watch`
+acts the same as `--concurrency` for `deploy`, in that it will deploy or
+hotswap your stacks while respecting inter-stack dependencies.
+
+```console
+$ cdk watch --concurrency 5
+```
+
 **Note**: This command is considered experimental, and might have breaking changes in the future.
 The same limitations apply to to `watch` deployments as do to `--hotswap` deployments. See the
 *Hotswap deployments for faster development* section for more information.

packages/aws-cdk/lib/cdk-toolkit.ts

@@ -737,6 +737,7 @@ export class CdkToolkit {
       cacheCloudAssembly: false,
       hotswap: hotswap,
       extraUserAgent: `cdk-watch/hotswap-${hotswap ? 'on' : 'off'}`,
+      concurrency: options.concurrency,
     };
 
     try {
@@ -900,6 +901,14 @@ interface WatchOptions extends Omit<CfnDeployOptions, 'execute'> {
    * @default - false
    */
   readonly traceLogs?: boolean;
+
+  /**
+   * Maximum number of simulatenous deployments (dependency permitting) to execute.
+   * The default is '1', which executes all deployments serially.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
 }
 
 export interface DeployOptions extends CfnDeployOptions, WatchOptions {

packages/aws-cdk/lib/cli.ts

@@ -216,7 +216,8 @@ async function parseCommandLineArguments() {
         default: true,
         desc: 'Show CloudWatch log events from all resources in the selected Stacks in the terminal. ' +
           "'true' by default, use --no-logs to turn off",
-      }),
+      })
+      .option('concurrency', { type: 'number', desc: 'Maximum number of simulatenous deployments (dependency permitting) to execute.', default: 1, requiresArg: true }),
     )
     .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', (yargs: Argv) => yargs
       .option('all', { type: 'boolean', default: false, desc: 'Destroy all available stacks' })
@@ -516,6 +517,7 @@ async function initCommandLine() {
           rollback: configuration.settings.get(['rollback']),
           hotswap: args.hotswap,
           traceLogs: args.logs,
+          concurrency: args.concurrency,
         });
 
       case 'destroy':

packages/aws-cdk/test/cdk-toolkit.test.ts

@@ -657,6 +657,18 @@ describe('watch', () => {
     expect(excludeArgs[1]).toBe('**/my-dir2');
   });
 
+  test('allows watching with deploy concurrency', async () => {
+    cloudExecutable.configuration.settings.set(['watch'], {});
+    const toolkit = defaultToolkitSetup();
+    const cdkDeployMock = jest.fn();
+    toolkit.deploy = cdkDeployMock;
+
+    await toolkit.watch({ selector: { patterns: [] }, concurrency: 3 });
+    fakeChokidarWatcherOn.readyCallback();
+
+    expect(cdkDeployMock).toBeCalledWith(expect.objectContaining({ concurrency: 3 }));
+  });
+
   describe('with file change events', () => {
     let toolkit: CdkToolkit;
     let cdkDeployMock: jest.Mock;