feat(core): support discriminator option in uniqueResourceName

[jasdeepbhalla]

Issue

Closes #36606.

Reason for this change

Previously, calling Names.uniqueResourceName() multiple times with the same construct would always return the same name because the hash calculation was solely based on the construct's path. This made it impossible to generate multiple different unique names for child resources that need to be created before the child constructs are initialized.

Use Case:
When creating multiple child resources that require unique physical names, developers need to call uniqueResourceName before the child constructs are initialized. Since they can only pass the parent construct (this), they get the same name for all resources, causing conflicts.

Example of the problem:

// These all return the same name
const name1 = Names.uniqueResourceName(this);
const name2 = Names.uniqueResourceName(this);

new SomeResource(this, 'SomeResource1', {
  name: name1,  // Need a unique name here
});

new SomeResource(this, 'SomeResource2', {
  name: name2,  // Need a different unique name here
});

Description of changes

Core Implementation:

1. Added discriminator?: string option to UniqueResourceNameOptions interface in names.ts
2. Updated pathHash() function in unique-resource-name.ts to include discriminator in the MD5 hash calculation when provided
3. Modified top-level resource logic to always include a hash when discriminator is present (even for short names) to ensure uniqueness
4. Made the options parameter optional with default empty object for better API ergonomics

How it works:

• The discriminator is included in the hash calculation: hashInput = discriminator ? ${pathString}/${discriminator} : pathString
• The discriminator is NOT included in the human-readable portion, maintaining consistent output length
• Different discriminators produce different hashes, ensuring unique names
• Same discriminator always produces the same name (deterministic)

Design decisions:

• Discriminator in hash only: We considered including it in the human-readable part, but that would change output length and make names less readable. Including it only in the hash keeps names consistent and clean.
• Optional parameter: Made discriminator optional to maintain backward compatibility. Existing code continues to work without modification.
• Hash always included with discriminator: When a discriminator is provided, we always add a hash (even for short top-level resources) to guarantee uniqueness. This ensures the feature works reliably in all cases.

Alternatives considered:

1. Creating empty constructs: Users could create dummy constructs just for name generation, but this pollutes the construct tree unnecessarily
2. Using Lazy: Users could defer name resolution with Lazy.string(), but this is verbose and requires using Lazy for every resource
3. Manual name construction: Users could manually construct names like ${Stack.of(this).stackName}-${this.node.id}-ABC, but this loses the hash-based uniqueness guarantee

The discriminator approach is the cleanest solution that maintains all the benefits of uniqueResourceName while solving the multiple-names-from-same-construct problem.

Describe any new or updated permissions being added

No new or updated IAM permissions are required. This change only affects the core CDK library's name generation utility and does not interact with any AWS services or require additional permissions.

Description of how you validated changes

Unit Tests:

• Added comprehensive unit tests in names.test.ts for the public API:

  • Different discriminators produce different names
  • Same discriminator produces same name
  • Behavior without discriminator remains unchanged
  • Discriminator is included in hash but not human-readable portion

• Added unit tests in unique-resource-name.test.ts for the private implementation:

  • Discriminator produces different names for same path
  • Same discriminator produces same name
  • Discriminator forces hash inclusion even for short top-level resources
  • Discriminator works with separators and other options

Integration Test:

• Created integ.unique-resource-name-discriminator.ts that:
  • Generates multiple unique names from the same construct using different discriminators
  • Creates real AWS resources (SQS queues) with those names
  • Verifies that CloudFormation deployment succeeds (would fail if names weren't unique)
  • Tests backward compatibility by creating a queue without discriminator

Documentation:

• Updated top-level aws-cdk-lib/README.md with a new "Names" section
• Enhanced JSDoc comments in names.ts with @example tags showing discriminator usage

Manual Testing:

• Verified that existing code patterns continue to work
• Confirmed that names generated with discriminators are unique and deterministic
• Validated that output length remains consistent regardless of discriminator value

All tests pass and the implementation follows existing codebase patterns and conventions.

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

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	48 ran	48 passed

Test	Result
No test annotations available

• View Security Guardian Results

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	48 ran	48 passed

Test	Result
No test annotations available

• View Security Guardian Results with resolved templates

[aws-cdk-automation]

This PR has been in the MERGE CONFLICTS state for 3 weeks, and looks abandoned. Note that PRs with failing linting check or builds are not reviewed, please ensure your build is passing

To prevent automatic closure:

• Resume work on the PR
• OR request an exemption by adding a comment containing 'Exemption Request' with justification e.x "Exemption Request: "
• OR request clarification by adding a comment containing 'Clarification Request' with a question e.x "Clarification Request: "

This PR will automatically close in 14 days if no action is taken.