feat(toolkit-lib): add watchValidate action and cdk validate --watch

[iankhou]

#1762

Adds a watch mode for validation that continuously re-synthesizes and re-validates the app on file changes. It never deploys.

toolkit-lib

• New public Toolkit.watchValidate(cx, options) returning IWatcher, built on the private _watch combinator. Each iteration runs the validate action.
• New WatchValidateOptions composing WatchFileOptions with ValidateOptions.
• Validation errors (e.g. synth failures mid-edit) are reported and swallowed so the watch loop survives and re-validates on the next change.

CLI

• New --watch flag on cdk validate.
• CdkToolkit.validate() delegates to toolkit.watchValidate() when watch is requested, reading include/exclude from the same "watch" key in cdk.json as cdk deploy --watch, and passing an uncached assembly source so every iteration re-synthesizes.

Usage

cdk validate --unstable=validate --watch [STACKS..] [--no-online]

Testing

Tested on sample app for:

• cdk validate --watch
• Test on online validation (S3 bucket name conflict)
• cdk validate --watch --no-online
• Test on annotation (S3 encryption policy)

Ensured stack re-validated after syntax and validation errors.

Checklist

• Unit tests added/updated (toolkit-lib watch-validate.test.ts, cdk-toolkit.test.ts)
• Integration tests added/updated (not deploying new resource types)
• No manual edits to generated files (parser regenerated)

---

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

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Adds a new “watch mode” for validate across both the CLI (cdk validate --watch) and @aws-cdk/toolkit-lib, enabling continuous re-synthesis and re-validation on file changes without deploying. This extends the existing watch infrastructure to cover validation workflows and wires CLI configuration (cdk.json "watch" include/exclude) into the new mode.

Changes:

• Add Toolkit.watchValidate(cx, options): Promise<IWatcher> built on the private _watch loop, invoking validate each iteration and swallowing/reporting validation/synth errors to keep watching.
• Add cdk validate --watch flag, delegating from CdkToolkit.validate() to toolkit.watchValidate() with watch include/exclude from cdk.json and an uncached assembly source to force re-synthesis per iteration.
• Add unit tests for both toolkit-lib watch-validate behavior and CLI delegation/config handling.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/aws-cdk/test/cli/cdk-toolkit.test.ts	Adds unit tests asserting validate --watch delegation, config error handling, include/exclude propagation, and uncached re-synthesis behavior.
packages/aws-cdk/lib/cxapp/cloud-executable.ts	Adds uncachedSource() helper to force re-synthesis on every produce() for watch-style loops.
packages/aws-cdk/lib/cli/user-input.ts	Regenerates CLI user input types to include validate.watch.
packages/aws-cdk/lib/cli/parse-command-line-arguments.ts	Regenerates arg parser to add --watch to validate.
packages/aws-cdk/lib/cli/convert-to-user-input.ts	Plumbs watch through yargs/config conversion for validate.
packages/aws-cdk/lib/cli/cli.ts	Wires args.watch into the validate command execution path.
packages/aws-cdk/lib/cli/cli-type-registry.json	Updates generated command metadata to include validate.watch.
packages/aws-cdk/lib/cli/cli-config.ts	Adds watch option to the source-of-truth CLI config for validate.
packages/aws-cdk/lib/cli/cdk-toolkit.ts	Implements validateWatch() and routes validate() to watch mode when requested.
packages/@aws-cdk/toolkit-lib/test/actions/watch-validate.test.ts	Adds unit tests for the new Toolkit.watchValidate() behavior (initial run, re-run on changes, batching, error survival, dispose).
packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts	Adds new public watchValidate() method implemented via _watch.
packages/@aws-cdk/toolkit-lib/lib/actions/watch/index.ts	Introduces WatchValidateOptions as WatchFileOptions & ValidateOptions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

packages/aws-cdk/lib/cli/cdk-toolkit.ts:667

• The comment above exclude is a bit misleading: because this code always passes an exclude array (even when empty), toolkit-lib’s watch loop will not apply its WATCH_EXCLUDE_DEFAULTS (it only uses them when exclude is undefined). If the intent is to disable those defaults (e.g., to align with CLI watch behavior), it would help to document that explicitly here to avoid future confusion.

    // Pass the user's excludes explicitly; toolkit-lib always appends the
    // outdir, dot-file, and node_modules excludes on top of these.

packages/aws-cdk/lib/cli/cdk-toolkit.ts:1642

• The JSDoc here says @default false, but the CLI parsing/config plumbing treats this flag as optional (defaulting to undefined unless explicitly set). For consistency with other CLI options (and with packages/aws-cdk/lib/cli/user-input.ts), the documented default should be - undefined.

  /**
   * Continuously observe the project files, and re-validate automatically when changes are detected
   *
   * @default false
   */

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

packages/aws-cdk/lib/cli/cdk-toolkit.ts:1642

• The JSDoc here says @default false, but the CLI flag is optional and the parser default is undefined (i.e., unset unless --watch is provided). Keeping the docs aligned avoids implying that watch mode is enabled/disabled by default.

  /**
   * Continuously observe the project files, and re-validate automatically when changes are detected
   *
   * @default false
   */