feat(core): throw typed Errors (#34587)

### Issue 

Closes #32569 

### Description of changes

Throw typed errors everywhere.

This introduced a new error type `ExecutionError` that is meant for failures from external scripts or code.

### Describe any new or updated permissions being added

n/a

### Description of how you validated changes

Existing tests. Exemptions granted as this is a refactor of existing code.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

Author: mrgrain

packages/aws-cdk-lib/.eslintrc.js

@@ -15,11 +15,8 @@ baseConfig.rules['import/no-extraneous-dependencies'] = [
 
 // no-throw-default-error
 baseConfig.rules['@cdklabs/no-throw-default-error'] = ['error'];
-// not yet supported
-const noThrowDefaultErrorNotYetSupported = [
-  'core',
-];
 baseConfig.overrides.push({
+  rules: { "@cdklabs/no-throw-default-error": "off" },
   files: [
     // Build and test files can have whatever error they like
     "./scripts/**",
@@ -28,11 +25,7 @@ baseConfig.overrides.push({
 
     // Lambda Runtime code should use regular errors
     "./custom-resources/lib/provider-framework/runtime/**",
-
-    // Not yet supported modules
-    ...noThrowDefaultErrorNotYetSupported.map(m => `./${m}/lib/**`)
   ],
-  rules: { "@cdklabs/no-throw-default-error": "off" },
 });
 
 module.exports = baseConfig;

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

@@ -1,5 +1,6 @@
 import { IConstruct, MetadataEntry } from 'constructs';
 import { App } from './app';
+import { UnscopedValidationError } from './errors';
 import * as cxschema from '../../cloud-assembly-schema';
 import * as cxapi from '../../cx-api';
 
@@ -127,7 +128,7 @@ export class Annotations {
 
     // throw if CDK_BLOCK_DEPRECATIONS is set
     if (process.env.CDK_BLOCK_DEPRECATIONS) {
-      throw new Error(`${this.scope.node.path}: ${text}`);
+      throw new UnscopedValidationError(`${this.scope.node.path}: ${text}`);
     }
 
     this.addWarningV2(`Deprecated:${api}`, text);

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

@@ -1,4 +1,5 @@
 import { Fn } from './cfn-fn';
+import { UnscopedValidationError } from './errors';
 import { Stack } from './stack';
 import { Token } from './token';
 import { filterUndefined } from './util';
@@ -141,7 +142,7 @@ export class Arn {
 
     // Catch both 'null' and 'undefined'
     if (partition == null || region == null || account == null) {
-      throw new Error(`Arn.format: partition (${partition}), region (${region}), and account (${account}) must all be passed if stack is not passed.`);
+      throw new UnscopedValidationError(`Arn.format: partition (${partition}), region (${region}), and account (${account}) must all be passed if stack is not passed.`);
     }
 
     const sep = components.sep ?? (components.arnFormat === ArnFormat.COLON_RESOURCE_NAME ? ':' : '/');
@@ -153,7 +154,7 @@ export class Arn {
     ];
 
     if (sep !== '/' && sep !== ':' && sep !== '') {
-      throw new Error('resourcePathSep may only be ":", "/" or an empty string');
+      throw new UnscopedValidationError('resourcePathSep may only be ":", "/" or an empty string');
     }
 
     if (components.resourceName != null) {
@@ -324,10 +325,10 @@ export class Arn {
     // resource type (to notify authors of incorrect assumptions right away).
     const parsed = Arn.split(arn, ArnFormat.SLASH_RESOURCE_NAME);
     if (!Token.isUnresolved(parsed.resource) && parsed.resource !== resourceType) {
-      throw new Error(`Expected resource type '${resourceType}' in ARN, got '${parsed.resource}' in '${arn}'`);
+      throw new UnscopedValidationError(`Expected resource type '${resourceType}' in ARN, got '${parsed.resource}' in '${arn}'`);
     }
     if (!parsed.resourceName) {
-      throw new Error(`Expected resource name in ARN, didn't find one: '${arn}'`);
+      throw new UnscopedValidationError(`Expected resource name in ARN, didn't find one: '${arn}'`);
     }
     return parsed.resourceName;
   }
@@ -411,7 +412,7 @@ function parseArnShape(arn: string): 'token' | string[] {
     if (Token.isUnresolved(arn)) {
       return 'token';
     } else {
-      throw new Error(`ARNs must start with "arn:" and have at least 6 components: ${arn}`);
+      throw new UnscopedValidationError(`ARNs must start with "arn:" and have at least 6 components: ${arn}`);
     }
   }
 
@@ -423,17 +424,17 @@ function parseArnShape(arn: string): 'token' | string[] {
 
   const partition = components.length > 1 ? components[1] : undefined;
   if (!partition) {
-    throw new Error('The `partition` component (2nd component) of an ARN is required: ' + arn);
+    throw new UnscopedValidationError('The `partition` component (2nd component) of an ARN is required: ' + arn);
   }
 
   const service = components.length > 2 ? components[2] : undefined;
   if (!service) {
-    throw new Error('The `service` component (3rd component) of an ARN is required: ' + arn);
+    throw new UnscopedValidationError('The `service` component (3rd component) of an ARN is required: ' + arn);
   }
 
   const resource = components.length > 5 ? components[5] : undefined;
   if (!resource) {
-    throw new Error('The `resource` component (6th component) of an ARN is required: ' + arn);
+    throw new UnscopedValidationError('The `resource` component (6th component) of an ARN is required: ' + arn);
   }
 
   // Region can be missing in global ARNs (such as used by IAM)

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

@@ -1,4 +1,5 @@
 import { IConstruct } from 'constructs';
+import { ValidationError } from './errors';
 
 const ASPECTS_SYMBOL = Symbol.for('cdk-aspects');
 
@@ -178,7 +179,7 @@ export class AspectApplication {
    */
   public set priority(priority: number) {
     if (priority < 0) {
-      throw new Error('Priority must be a non-negative number');
+      throw new ValidationError('Priority must be a non-negative number', this.construct);
     }
     this._priority = priority;
 

packages/aws-cdk-lib/core/lib/asset-staging.ts

@@ -4,6 +4,7 @@ import { Construct } from 'constructs';
 import * as fs from 'fs-extra';
 import { AssetHashType, AssetOptions, FileAssetPackaging } from './assets';
 import { BundlingFileAccess, BundlingOptions, BundlingOutput } from './bundling';
+import { AssumptionError, ValidationError } from './errors';
 import { FileSystem, FingerprintOptions } from './fs';
 import { clearLargeFileFingerprintCache } from './fs/fingerprint';
 import { Names } from './names';
@@ -172,21 +173,21 @@ export class AssetStaging extends Construct {
     };
 
     if (!fs.existsSync(this.sourcePath)) {
-      throw new Error(`Cannot find asset at ${this.sourcePath}`);
+      throw new ValidationError(`Cannot find asset at ${this.sourcePath}`, this);
     }
 
     this.sourceStats = fs.statSync(this.sourcePath);
 
     const outdir = Stage.of(this)?.assetOutdir;
     if (!outdir) {
-      throw new Error('unable to determine cloud assembly asset output directory. Assets must be defined indirectly within a "Stage" or an "App" scope');
+      throw new ValidationError('unable to determine cloud assembly asset output directory. Assets must be defined indirectly within a "Stage" or an "App" scope', this);
     }
     this.assetOutdir = outdir;
 
     // Determine the hash type based on the props as props.assetHashType is
     // optional from a caller perspective.
     this.customSourceFingerprint = props.assetHash;
-    this.hashType = determineHashType(props.assetHashType, this.customSourceFingerprint);
+    this.hashType = determineHashType(this, props.assetHashType, this.customSourceFingerprint);
 
     // Decide what we're going to do, without actually doing it yet
     let stageThisAsset: () => StagedAsset;
@@ -284,7 +285,7 @@ export class AssetStaging extends Construct {
     const stagedPath = this.renderStagedPath(this.sourcePath, targetPath);
 
     if (!this.sourceStats.isDirectory() && !this.sourceStats.isFile()) {
-      throw new Error(`Asset ${this.sourcePath} is expected to be either a directory or a regular file`);
+      throw new ValidationError(`Asset ${this.sourcePath} is expected to be either a directory or a regular file`, this);
     }
 
     this.stageAsset(this.sourcePath, stagedPath, 'copy');
@@ -304,7 +305,7 @@ export class AssetStaging extends Construct {
    */
   private stageByBundling(bundling: BundlingOptions, skip: boolean): StagedAsset {
     if (!this.sourceStats.isDirectory()) {
-      throw new Error(`Asset ${this.sourcePath} is expected to be a directory when bundling`);
+      throw new ValidationError(`Asset ${this.sourcePath} is expected to be a directory when bundling`, this);
     }
 
     if (skip) {
@@ -334,7 +335,7 @@ export class AssetStaging extends Construct {
 
     // Check bundling output content and determine if we will need to archive
     const bundlingOutputType = bundling.outputType ?? BundlingOutput.AUTO_DISCOVER;
-    const bundledAsset = determineBundledAsset(bundleDir, bundlingOutputType);
+    const bundledAsset = determineBundledAsset(this, bundleDir, bundlingOutputType);
 
     // Calculate assetHash afterwards if we still must
     assetHash = assetHash ?? this.calculateHash(this.hashType, bundling, bundledAsset.path);
@@ -404,7 +405,7 @@ export class AssetStaging extends Construct {
       fs.mkdirSync(targetPath);
       FileSystem.copyDirectory(sourcePath, targetPath, this.fingerprintOptions);
     } else {
-      throw new Error(`Unknown file type: ${sourcePath}`);
+      throw new ValidationError(`Unknown file type: ${sourcePath}`, this);
     }
   }
 
@@ -472,12 +473,12 @@ export class AssetStaging extends Construct {
       // Success, rename the tempDir into place
       fs.renameSync(tempDir, bundleDir);
     } catch (err) {
-      throw new Error(`Failed to bundle asset ${this.node.path}, bundle output is located at ${tempDir}: ${err}`);
+      throw new ValidationError(`Failed to bundle asset ${this.node.path}, bundle output is located at ${tempDir}: ${err}`, this);
     }
 
     if (FileSystem.isEmpty(bundleDir)) {
       const outputDir = localBundling ? bundleDir : AssetStaging.BUNDLING_OUTPUT_DIR;
-      throw new Error(`Bundling did not produce any output. Check that content is written to ${outputDir}.`);
+      throw new ValidationError(`Bundling did not produce any output. Check that content is written to ${outputDir}.`, this);
     }
   }
 
@@ -505,11 +506,11 @@ export class AssetStaging extends Construct {
       case AssetHashType.BUNDLE:
       case AssetHashType.OUTPUT:
         if (!outputDir) {
-          throw new Error(`Cannot use \`${hashType}\` hash type when \`bundling\` is not specified.`);
+          throw new ValidationError(`Cannot use \`${hashType}\` hash type when \`bundling\` is not specified.`, this);
         }
         return FileSystem.fingerprint(outputDir, this.fingerprintOptions);
       default:
-        throw new Error('Unknown asset hash type.');
+        throw new ValidationError('Unknown asset hash type.', this);
     }
   }
 
@@ -535,16 +536,16 @@ function renderAssetFilename(assetHash: string, extension = '') {
  * @param assetHashType Asset hash type construct prop
  * @param customSourceFingerprint Asset hash seed given in the construct props
  */
-function determineHashType(assetHashType?: AssetHashType, customSourceFingerprint?: string) {
+function determineHashType(scope: Construct, assetHashType?: AssetHashType, customSourceFingerprint?: string) {
   const hashType = customSourceFingerprint
     ? (assetHashType ?? AssetHashType.CUSTOM)
     : (assetHashType ?? AssetHashType.SOURCE);
 
   if (customSourceFingerprint && hashType !== AssetHashType.CUSTOM) {
-    throw new Error(`Cannot specify \`${assetHashType}\` for \`assetHashType\` when \`assetHash\` is specified. Use \`CUSTOM\` or leave \`undefined\`.`);
+    throw new ValidationError(`Cannot specify \`${assetHashType}\` for \`assetHashType\` when \`assetHash\` is specified. Use \`CUSTOM\` or leave \`undefined\`.`, scope);
   }
   if (hashType === AssetHashType.CUSTOM && !customSourceFingerprint) {
-    throw new Error('`assetHash` must be specified when `assetHashType` is set to `AssetHashType.CUSTOM`.');
+    throw new ValidationError('`assetHash` must be specified when `assetHashType` is set to `AssetHashType.CUSTOM`.', scope);
   }
 
   return hashType;
@@ -589,7 +590,7 @@ function sanitizeHashValue(key: string, value: any): any {
       }
     } catch (e: any) {
       if (e.name === 'TypeError') {
-        throw new Error(`${key} must be a valid URL, got ${value}.`);
+        throw new AssumptionError(`${key} must be a valid URL, got ${value}.`);
       }
       throw e;
     }
@@ -600,13 +601,13 @@ function sanitizeHashValue(key: string, value: any): any {
 /**
  * Returns the single archive file of a directory or undefined
  */
-function findSingleFile(directory: string, archiveOnly: boolean): string | undefined {
+function findSingleFile(scope: Construct, directory: string, archiveOnly: boolean): string | undefined {
   if (!fs.existsSync(directory)) {
-    throw new Error(`Directory ${directory} does not exist.`);
+    throw new ValidationError(`Directory ${directory} does not exist.`, scope);
   }
 
   if (!fs.statSync(directory).isDirectory()) {
-    throw new Error(`${directory} is not a directory.`);
+    throw new ValidationError(`${directory} is not a directory.`, scope);
   }
 
   const content = fs.readdirSync(directory);
@@ -631,8 +632,8 @@ interface BundledAsset {
  * Returns the bundled asset to use based on the content of the bundle directory
  * and the type of output.
  */
-function determineBundledAsset(bundleDir: string, outputType: BundlingOutput): BundledAsset {
-  const archiveFile = findSingleFile(bundleDir, outputType !== BundlingOutput.SINGLE_FILE);
+function determineBundledAsset(scope: Construct, bundleDir: string, outputType: BundlingOutput): BundledAsset {
+  const archiveFile = findSingleFile(scope, bundleDir, outputType !== BundlingOutput.SINGLE_FILE);
 
   // auto-discover means that if there is an archive file, we take it as the
   // bundle, otherwise, we will archive here.
@@ -646,7 +647,7 @@ function determineBundledAsset(bundleDir: string, outputType: BundlingOutput): B
     case BundlingOutput.ARCHIVED:
     case BundlingOutput.SINGLE_FILE:
       if (!archiveFile) {
-        throw new Error('Bundling output directory is expected to include only a single file when `output` is set to `ARCHIVED` or `SINGLE_FILE`');
+        throw new ValidationError('Bundling output directory is expected to include only a single file when `output` is set to `ARCHIVED` or `SINGLE_FILE`', scope);
       }
       return { path: archiveFile, packaging: FileAssetPackaging.FILE, extension: getExtension(archiveFile) };
   }

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

@@ -2,6 +2,7 @@ import { spawnSync } from 'child_process';
 import * as crypto from 'crypto';
 import { isAbsolute, join } from 'path';
 import { DockerCacheOption } from './assets';
+import { ExecutionError, UnscopedValidationError } from './errors';
 import { FileSystem } from './fs';
 import { dockerExec } from './private/asset-staging';
 import { quiet, reset } from './private/jsii-deprecated';
@@ -312,7 +313,7 @@ export class BundlingDockerImage {
     const { stdout } = dockerExec(['create', this.image], {}); // Empty options to avoid stdout redirect here
     const match = stdout.toString().match(/([0-9a-f]{16,})/);
     if (!match) {
-      throw new Error('Failed to extract container ID from Docker create output');
+      throw new ExecutionError('Failed to extract container ID from Docker create output');
     }
 
     const containerId = match[1];
@@ -322,7 +323,7 @@ export class BundlingDockerImage {
       dockerExec(['cp', containerPath, destPath]);
       return destPath;
     } catch (err) {
-      throw new Error(`Failed to copy files from ${containerPath} to ${destPath}: ${err}`);
+      throw new ExecutionError(`Failed to copy files from ${containerPath} to ${destPath}: ${err}`);
     } finally {
       dockerExec(['rm', '-v', containerId]);
     }
@@ -343,7 +344,7 @@ export class DockerImage extends BundlingDockerImage {
     const buildArgs = options.buildArgs || {};
 
     if (options.file && isAbsolute(options.file)) {
-      throw new Error(`"file" must be relative to the docker build directory. Got ${options.file}`);
+      throw new UnscopedValidationError(`"file" must be relative to the docker build directory. Got ${options.file}`);
     }
 
     // Image tag derived from path and build options

packages/aws-cdk-lib/core/lib/cfn-codedeploy-blue-green-hook.ts

@@ -1,6 +1,7 @@
 import { Construct } from 'constructs';
 import { CfnHook } from './cfn-hook';
 import { CfnResource } from './cfn-resource';
+import { UnscopedValidationError } from './errors';
 import { FromCloudFormationOptions } from './helpers-internal';
 import { undefinedIfAllValuesAreEmpty } from './util';
 
@@ -366,7 +367,7 @@ export class CfnCodeDeployBlueGreenHook extends CfnHook {
       }
       const ret = options.parser.finder.findResource(logicalId);
       if (!ret) {
-        throw new Error(`Hook '${id}' references resource '${logicalId}' that was not found in the template`);
+        throw new UnscopedValidationError(`Hook '${id}' references resource '${logicalId}' that was not found in the template`);
       }
       return ret;
     }

packages/aws-cdk-lib/core/lib/cfn-element.ts

@@ -84,8 +84,8 @@ export abstract class CfnElement extends Construct {
    */
   public overrideLogicalId(newLogicalId: string) {
     if (this._logicalIdLocked) {
-      throw new Error(`The logicalId for resource at path ${Node.of(this).path} has been locked and cannot be overridden\n` +
-        'Make sure you are calling "overrideLogicalId" before Stack.exportValue');
+      throw new ValidationError(`The logicalId for resource at path ${Node.of(this).path} has been locked and cannot be overridden\n` +
+        'Make sure you are calling "overrideLogicalId" before Stack.exportValue', this);
     } else {
       this._logicalIdOverride = newLogicalId;
     }
@@ -206,4 +206,5 @@ function notTooLong(x: string) {
 // These imports have to be at the end to prevent circular imports
 import { CfnReference } from './private/cfn-reference';
 import { Stack } from './stack';
-import { Token } from './token';
+import { Token } from './token';import { ValidationError } from './errors';
+