Merge branch 'main' into mrgrain/feat/lambda/validation-error

.github/workflows/github-merit-badger.yml

@@ -17,4 +17,4 @@ jobs:
           badges: '[beginning-contributor,repeat-contributor,valued-contributor,admired-contributor,star-contributor,distinguished-contributor]'
           thresholds: '[0,3,6,13,25,50]'
           badge-type: 'achievement'
-          ignore-usernames: '[rix0rrr,iliapolo,otaviomacedo,kaizencc,comcalvi,TheRealAmazonKendra,mrgrain,pahud,kellertk,ashishdhingra,HBobertz,sumupitchayan,colifran,khushail,moelasmar,paulhcsun,GavinZZ,aaythapa,xazhao,gracelu0,jfuss,shikha372,kirtishrinkhala,godwingrs22,bergjaak,IanKonlog,Leo10Gama,samson-keung,scorbiere,michelle-wangg,jiayiwang7,1kaileychen,saiyush,5d,iankhou,aws-cdk-automation,dependabot[bot],mergify[bot]]'
+          ignore-usernames: '[rix0rrr,iliapolo,otaviomacedo,kaizencc,comcalvi,TheRealAmazonKendra,mrgrain,pahud,kellertk,ashishdhingra,HBobertz,colifran,khushail,moelasmar,paulhcsun,GavinZZ,aaythapa,xazhao,gracelu0,jfuss,shikha372,kirtishrinkhala,godwingrs22,bergjaak,IanKonlog,Leo10Gama,samson-keung,scorbiere,michelle-wangg,jiayiwang7,1kaileychen,saiyush,5d,iankhou,aws-cdk-automation,dependabot[bot],mergify[bot]]'

.mergify.yml

@@ -45,7 +45,7 @@ pull_request_rules:
       label:
         add: [ contribution/core ]
     conditions:
-      - author~=^(rix0rrr|iliapolo|otaviomacedo|kaizencc|comcalvi|TheRealAmazonKendra|mrgrain|pahud|ashishdhingra|kellertk|HBobertz|sumupitchayan|colifran|moelasmar|paulhcsun|GavinZZ|aaythapa|xazhao|gracelu0|jfuss|shikha372|kirtishrinkhala|godwingrs22|bergjaak|samson-keung|IanKonlog|Leo10Gama|scorbiere|michelle-wangg|jiayiwang7|1kaileychen|saiyush|5d|iankhou)$
+      - author~=^(rix0rrr|iliapolo|otaviomacedo|kaizencc|comcalvi|TheRealAmazonKendra|mrgrain|pahud|ashishdhingra|kellertk|HBobertz|colifran|moelasmar|paulhcsun|GavinZZ|aaythapa|xazhao|gracelu0|jfuss|shikha372|kirtishrinkhala|godwingrs22|bergjaak|samson-keung|IanKonlog|Leo10Gama|scorbiere|michelle-wangg|jiayiwang7|1kaileychen|saiyush|5d|iankhou)$
       - -label~="contribution/core"
   - name: automatic merge
     actions:

packages/aws-cdk-lib/core/lib/errors.ts

@@ -5,18 +5,24 @@ const CONSTRUCT_ERROR_SYMBOL = Symbol.for('@aws-cdk/core.SynthesisError');
 const VALIDATION_ERROR_SYMBOL = Symbol.for('@aws-cdk/core.ValidationError');
 
 /**
- * Helper to check if an error is a SynthesisErrors
+ * Helper to check if an error is of a certain type.
  */
 export class Errors {
   /**
-   * Test whether the given errors is a ConstructionError
+   * Test whether the given errors is a ConstructionError.
+   *
+   * A ConstructionError is a generic error that will be thrown during the App construction or synthesis.
+   * To check for more specific errors, use the respective methods.
    */
   public static isConstructError(x: any): x is ConstructError {
     return x !== null && typeof(x) === 'object' && CONSTRUCT_ERROR_SYMBOL in x;
   }
 
   /**
-   * Test whether the given error is a ValidationError
+   * Test whether the given error is a ValidationError.
+   *
+   * A ValidationError is thrown when input props are failing to pass the rules of the construct.
+   * It usually means the underlying CloudFormation resource(s) would not deploy with a given configuration.
    */
   public static isValidationError(x: any): x is ValidationError {
     return Errors.isConstructError(x) && VALIDATION_ERROR_SYMBOL in x;
@@ -29,7 +35,7 @@ interface ConstructInfo {
 }
 
 /**
- * Generic, abstract error that is thrown from the users app during app construction or synth.
+ * Generic, abstract error class used for errors thrown from the users app during construction or synth.
  */
 abstract class ConstructError extends Error {
   #time: string;
@@ -130,7 +136,12 @@ abstract class ConstructError extends Error {
 }
 
 /**
- * An Error that is thrown when a construct has validation errors.
+ * A ValidationError should be used when input props fail to pass the validation rules of a construct
+ * or class or late binding. The error indicates that the underlying CloudFormation resource(s) would
+ * not deploy with a given configuration, or that some other prerequisites are not met.
+ *
+ * A ValidationError is always attached to a Construct scope. To a user, the error will present with additional
+ * information on the construct that caused the validation to fail.
  */
 export class ValidationError extends ConstructError {
   public get type(): 'validation' {
@@ -145,7 +156,12 @@ export class ValidationError extends ConstructError {
 }
 
 /**
- * An Error that is thrown when a class has validation errors.
+ * An UnscopedValidationError is a ValidationError that is not attached to a specific construct.
+ * This can be used to report validation errors that are thrown when no construct scope is available.
+ * The common use case here are data classes that assert on props, but are not constructs itself.
+ *
+ * To a User, these errors still present themselves as a "ValidationError".
+ * However they do not contain any information about the location in the construct tree.
  */
 export class UnscopedValidationError extends ConstructError {
   public get type(): 'validation' {