feat(mixins-preview): strongly-typed ConstructSelector interface

Changed `Mixins.of()` to take a `IConstructSelector` instead of only one of the provided selectors. This allows users to implement custom selectors.

Added `ConstructSelector.byPath()` to match on a construct path, to complement the existing `byId()`.

BREAKING CHANGE: `ConstructSelector.byId()` now takes a glob pattern instead of a regular expression.

BREAKING CHANGE: `ConstructSelector.resourcesOfType()` now must receive a string.

Author: mrgrain

package.json

@@ -95,9 +95,9 @@
       "scripts/@aws-cdk/script-tests"
     ],
     "nohoist": [
+      "**/@types/glob",
       "**/jszip",
       "**/jszip/**",
-      "**/@types/glob",
       "@aws-cdk/assertions-alpha/fs-extra",
       "@aws-cdk/assertions-alpha/fs-extra/**",
       "@aws-cdk/assertions/fs-extra",
@@ -146,6 +146,8 @@
       "@aws-cdk/core/yaml/**",
       "@aws-cdk/cx-api/semver",
       "@aws-cdk/cx-api/semver/**",
+      "@aws-cdk/mixins-preview/minimatch",
+      "@aws-cdk/mixins-preview/minimatch/**",
       "@aws-cdk/pipelines/aws-sdk",
       "@aws-cdk/pipelines/aws-sdk/**",
       "@aws-cdk/yaml-cfn/yaml",

packages/@aws-cdk/mixins-preview/README.md

@@ -95,11 +95,11 @@ Mixins operate on construct trees and can be applied selectively:
 Mixins.of(scope).apply(new EncryptionAtRest());
 
 // Apply to specific resource types
-Mixins.of(scope, ConstructSelector.resourcesOfType(s3.CfnBucket))
+Mixins.of(scope, ConstructSelector.resourcesOfType(s3.CfnBucket.CFN_RESOURCE_TYPE_NAME))
   .apply(new EncryptionAtRest());
 
-// Apply to constructs matching a pattern
-Mixins.of(scope, ConstructSelector.byId(/.*-prod-.*/))
+// Apply to constructs matching a path pattern
+Mixins.of(scope, ConstructSelector.byPath("**/*-prod-*/**"))
   .apply(new ProductionSecurityMixin());
 ```
 

packages/@aws-cdk/mixins-preview/lib/core/applicator.ts

@@ -1,18 +1,18 @@
 import type { IConstruct } from 'constructs';
 import { ValidationError } from 'aws-cdk-lib/core';
 import type { IMixin } from './mixins';
-import { ConstructSelector } from './selectors';
+import { ConstructSelector, type IConstructSelector } from './selectors';
 
 /**
  * Applies mixins to constructs.
  */
 export class MixinApplicator {
   private readonly scope: IConstruct;
-  private readonly selector: ConstructSelector;
+  private readonly selector: IConstructSelector;
 
   constructor(
     scope: IConstruct,
-    selector: ConstructSelector = ConstructSelector.all(),
+    selector: IConstructSelector = ConstructSelector.all(),
   ) {
     this.scope = scope;
     this.selector = selector;

packages/@aws-cdk/mixins-preview/lib/core/mixins.ts

@@ -1,5 +1,5 @@
 import type { IConstruct } from 'constructs';
-import type { ConstructSelector } from './selectors';
+import type { IConstructSelector } from './selectors';
 import { MixinApplicator } from './applicator';
 
 // this will change when we update the interface to deliberately break compatibility checks
@@ -12,7 +12,7 @@ export class Mixins {
   /**
    * Creates a MixinApplicator for the given scope.
    */
-  static of(scope: IConstruct, selector?: ConstructSelector): MixinApplicator {
+  static of(scope: IConstruct, selector?: IConstructSelector): MixinApplicator {
     return new MixinApplicator(scope, selector);
   }
 }

packages/@aws-cdk/mixins-preview/lib/core/selectors.ts

@@ -1,58 +1,72 @@
-import type { IConstruct } from 'constructs';
+import type { IConstruct, Node } from 'constructs';
 import { CfnResource } from 'aws-cdk-lib/core';
 
+/**
+ * Selects constructs from a construct tree.
+ */
+export interface IConstructSelector {
+  /**
+   * Selects constructs from the given scope based on the selector's criteria.
+   */
+  select(scope: IConstruct): IConstruct[];
+}
+
 /**
  * Selects constructs from a construct tree based on various criteria.
  */
-export abstract class ConstructSelector {
+export class ConstructSelector {
   /**
    * Selects all constructs in the tree.
    */
-  static all(): ConstructSelector {
+  static all(): IConstructSelector {
     return new AllConstructsSelector();
   }
 
   /**
    * Selects CfnResource constructs or the default CfnResource child.
    */
-  static cfnResource(): ConstructSelector {
+  static cfnResource(): IConstructSelector {
     return new CfnResourceSelector();
   }
 
   /**
    * Selects only the provided construct.
    */
-  static onlyItself(): ConstructSelector {
+  static onlyItself(): IConstructSelector {
     return new OnlyItselfSelector();
   }
 
   /**
    * Selects constructs of a specific type.
    */
-  static resourcesOfType(type: string | any): ConstructSelector {
-    return new ResourceTypeSelector(type);
+  static resourcesOfType(...types: string[]): IConstructSelector {
+    return new ResourceTypeSelector(types);
   }
 
   /**
-   * Selects constructs whose IDs match a pattern.
+   * Selects constructs whose construct IDs match a pattern.
+   * Uses glob like matching.
    */
-  static byId(pattern: any): ConstructSelector {
-    return new IdPatternSelector(pattern);
+  static byId(pattern: string): IConstructSelector {
+    return new IdPatternSelector(pattern, 'id');
   }
 
   /**
-   * Selects constructs from the given scope based on the selector's criteria.
+   * Selects constructs whose construct paths match a pattern.
+   * Uses glob like matching.
    */
-  abstract select(scope: IConstruct): IConstruct[];
+  static byPath(pattern: string): IConstructSelector {
+    return new IdPatternSelector(pattern, 'path');
+  }
 }
 
-class AllConstructsSelector extends ConstructSelector {
+class AllConstructsSelector implements IConstructSelector {
   select(scope: IConstruct): IConstruct[] {
     return scope.node.findAll();
   }
 }
 
-class CfnResourceSelector extends ConstructSelector {
+class CfnResourceSelector implements IConstructSelector {
   select(scope: IConstruct): IConstruct[] {
     if (CfnResource.isCfnResource(scope)) {
       return [scope];
@@ -65,26 +79,15 @@ class CfnResourceSelector extends ConstructSelector {
   }
 }
 
-class ResourceTypeSelector extends ConstructSelector {
-  constructor(private readonly type: string | any) {
-    super();
+class ResourceTypeSelector implements IConstructSelector {
+  constructor(private readonly types: string[]) {
   }
 
   select(scope: IConstruct): IConstruct[] {
     const result: IConstruct[] = [];
     const visit = (node: IConstruct) => {
-      if (typeof this.type === 'string') {
-        if (CfnResource.isCfnResource(node) && node.cfnResourceType === this.type) {
-          result.push(node);
-        }
-      } else if ('isCfnResource' in this.type && 'CFN_RESOURCE_TYPE_NAME' in this.type) {
-        if (CfnResource.isCfnResource(node) && node.cfnResourceType === this.type.CFN_RESOURCE_TYPE_NAME) {
-          result.push(node);
-        }
-      } else {
-        if (node instanceof this.type) {
-          result.push(node);
-        }
+      if (CfnResource.isCfnResource(node) && this.types.includes(node.cfnResourceType)) {
+        result.push(node);
       }
       for (const child of node.node.children) {
         visit(child);
@@ -95,15 +98,17 @@ class ResourceTypeSelector extends ConstructSelector {
   }
 }
 
-class IdPatternSelector extends ConstructSelector {
-  constructor(private readonly pattern: any) {
-    super();
-  }
+// Must be a 'require' to not run afoul of ESM module import rules
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const minimatch = require('minimatch');
+
+class IdPatternSelector implements IConstructSelector {
+  constructor(private readonly pattern: string, private field: keyof Node) {}
 
   select(scope: IConstruct): IConstruct[] {
     const result: IConstruct[] = [];
     const visit = (node: IConstruct) => {
-      if (this.pattern && typeof this.pattern.test === 'function' && this.pattern.test(node.node.id)) {
+      if (minimatch(node.node[this.field], this.pattern)) {
         result.push(node);
       }
       for (const child of node.node.children) {
@@ -115,7 +120,7 @@ class IdPatternSelector extends ConstructSelector {
   }
 }
 
-class OnlyItselfSelector extends ConstructSelector {
+class OnlyItselfSelector implements IConstructSelector {
   select(scope: IConstruct): IConstruct[] {
     return [scope];
   }

packages/@aws-cdk/mixins-preview/package.json

@@ -648,6 +648,7 @@
     "url": "https://aws.amazon.com",
     "organization": true
   },
+  "homepage": "https://github.com/aws/aws-cdk",
   "license": "Apache-2.0",
   "devDependencies": {
     "@aws-cdk/cdk-build-tools": "0.0.0",
@@ -665,7 +666,12 @@
     "jest": "^29.7.0",
     "tsx": "^4.20.6"
   },
-  "homepage": "https://github.com/aws/aws-cdk",
+  "dependencies": {
+    "minimatch": "^3.1.2"
+  },
+  "bundleDependencies": [
+    "minimatch"
+  ],
   "peerDependencies": {
     "aws-cdk-lib": "^0.0.0",
     "constructs": "^10.0.0"

packages/@aws-cdk/mixins-preview/test/core/selectors.test.ts

@@ -33,7 +33,7 @@ describe('ConstructSelector', () => {
     const bucket = new s3.CfnBucket(stack, 'Bucket');
     const logGroup = new logs.CfnLogGroup(stack, 'LogGroup');
 
-    const selected = ConstructSelector.resourcesOfType(s3.CfnBucket).select(stack);
+    const selected = ConstructSelector.resourcesOfType(s3.CfnBucket.CFN_RESOURCE_TYPE_NAME).select(stack);
     expect(selected).toContain(bucket);
     expect(selected).not.toContain(logGroup);
   });
@@ -51,7 +51,17 @@ describe('ConstructSelector', () => {
     const prodBucket = new s3.CfnBucket(stack, 'prod-bucket');
     const devBucket = new s3.CfnBucket(stack, 'dev-bucket');
 
-    const selected = ConstructSelector.byId(/prod-.*/).select(stack);
+    const selected = ConstructSelector.byId('*prod*').select(stack);
+    expect(selected).toContain(prodBucket);
+    expect(selected).not.toContain(devBucket);
+  });
+
+  test('byPath() selects by construct path pattern', () => {
+    const scope = new Construct(stack, 'Prefix');
+    const prodBucket = new s3.CfnBucket(scope, 'prod-bucket');
+    const devBucket = new s3.CfnBucket(stack, 'dev-bucket');
+
+    const selected = ConstructSelector.byPath('*/Prefix/**').select(stack);
     expect(selected).toContain(prodBucket);
     expect(selected).not.toContain(devBucket);
   });

packages/@aws-cdk/mixins-preview/test/mixins/full-example.ts

@@ -25,13 +25,13 @@ describe('Integration Tests', () => {
     // Apply encryption only to production buckets
     Mixins.of(
       stack,
-      ConstructSelector.byId(/.*Prod.*/),
+      ConstructSelector.byId('*Prod*'),
     ).apply(new s3Mixins.AutoDeleteObjects());
 
     // Apply versioning to all S3 buckets
     Mixins.of(
       stack,
-      ConstructSelector.resourcesOfType(s3.CfnBucket),
+      ConstructSelector.resourcesOfType(s3.CfnBucket.CFN_RESOURCE_TYPE_NAME),
     ).apply(new s3Mixins.EnableVersioning());
 
     // Verify auto-delete only applied to prod bucket