chore(core): refactor reflection helpers into PropertyReflection and ConstructReflection classes

[mrgrain]

Reason for this change

The generic reflection helpers in core/lib/helpers-internal/reflections.ts were a collection of loosely related free functions (resolvedGet, resolvedExists, resolvedEquals, findClosestRelatedResource, findL1FromRef, findParentL2Scope). The naming used L1/L2 jargon, the signatures were inconsistent between functions, and the property traversal logic was duplicated three times. The free-function style also made it harder to discover the available reflection capabilities.

Description of changes

This refactors the reflection helpers into two focused classes with a consistent API shape, each in its own file.

PropertyReflection provides token-aware property inspection on CfnResource instances. A single of(resource, path) call traverses the dot-separated path once, and the result can be queried with .exists(), .equals(expected), or .get(fallback). This replaces the three separate resolvedGet/resolvedExists/resolvedEquals functions that each re-traversed the path independently. The traversal now treats null the same as undefined (both are "missing") for consistency.

ConstructReflection provides construct tree search utilities. ConstructReflection.of(construct) creates an instance, then .findCfnResource(matcher) and .findRelatedCfnResource(matcher) search for CfnResources using a shared ICfnResourceMatcher interface. The defaultChildOwner getter replaces the old findParentL2Scope function. The method signatures are aligned and jsii-compatible — no generics on the public API, and the matcher interface can be implemented in any jsii language.

The duplicated KMS key matching logic (identical across S3, DynamoDB, SQS, and SNS) is extracted into a private CfnKeyMatcher class in aws-kms/lib/private/.

All internal consumers are updated. The old reflections.ts file is deleted.

Describe any new or updated permissions being added

None.

Description of how you validated changes

All existing tests pass. The test file is split to match the new file structure: property-reflection.test.ts (33 tests) covers PropertyReflection, and construct-reflection.test.ts (17 tests) covers ConstructReflection. The bucket-reflection.test.ts suite (32 tests) continues to provide integration-level coverage through BucketReflection.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mrgrain]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-04-08 16:19 UTC · Rule: default-squash
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged — 2026-04-08 16:19 UTC · at 704ac5cca37b8e07479388bbdb466f9b630bf34c

This pull request spent 14 seconds in the queue, including 2 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • chore(core): refactor reflection helpers into PropertyReflection and ConstructReflection classes #37352
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • chore(core): refactor reflection helpers into PropertyReflection and ConstructReflection classes #37352
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.