Remove DisplayName from the generic entitlement model

[Copilot]

• Remove DisplayName from all provider/step/test/doc files
• Fix PSSA warnings in previously-changed files
• Fix DisplayName in Generate-IdleStepReference.ps1 example (line 687) → regenerated step reference doc
• Fix empty catch block in Generate-IdleStepReference.ps1 — PSAvoidUsingEmptyCatchBlock
• Fix PSAvoidUsingPlainTextForPassword for $PasswordGenerationSpecialCharSet in New-IdleADAdapter.ps1 (SuppressMessageAttribute — false positive, parameter holds allowed characters not a password)
• Fix PSReviewUnusedParameter for $CurrentValue in New-IdleADAdapter.ps1 SetUser ScriptMethod ($null = $CurrentValue)
• Fix PSUseConsistentIndentation cascade (163 warnings) in New-IdleADAdapter.ps1 — root cause was multi-line pipeline with PipelineIndentation = IncreaseIndentationForFirstPipeline inside ScriptMethod not resetting depth; converted to single-line pipeline
• Fix PSUseConsistentWhitespace extra spaces around = on New-IdleADAdapter.ps1 line 834
• Remove trailing whitespace on blank lines 718/751 of New-IdleADAdapter.ps1
• Fix PSReviewUnusedParameter for $Request in Resolve-IdleTemplateString.ps1 (SuppressMessageAttribute — used inside nested scriptblock $resolvePath, PSSA cannot trace cross-scriptblock usage)
• Fix latent crash in Invoke-IdleScriptAnalyzer.ps1 when PSSA finds 0 results — added [AllowEmptyCollection()] to Write-PssaSummary's $Findings parameter
• PSSA: 0 warnings, 0 errors (down from 171)
• All 841 tests pass

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Remove DisplayName from the generic entitlement model</issue_title>
<issue_description>## Problem Statement

The generic entitlement model currently exposes a DisplayName field in addition to the functional identifier fields.

For a generic and provider-agnostic engine, entitlements should be identified deterministically by their stable identity, not by presentation metadata. In practice, DisplayName is ambiguous because it is provider-specific, may not be unique, may be mutable, and can suggest that entitlement matching or lookup by display value is supported or recommended.

Keeping DisplayName in the generic entitlement model increases semantic noise in the core domain model, creates documentation ambiguity, and makes examples less clear about which fields are actually required and authoritative.

Proposed Solution

Remove DisplayName from the generic entitlement model as a breaking change.

Scope:

• Remove DisplayName from the generic entitlement contract/domain model.
• Update all steps, providers, mock providers, examples, tests, and documentation so that entitlements are represented only by their functional fields.
• Ensure all entitlement examples consistently use Kind and Id only.
• Remove repository-wide references that imply DisplayName is part of the entitlement shape or that it may be used for matching.
• Review plan/debug/export examples and documentation and adjust wording/output expectations where needed.

Expected outcome:

• The generic entitlement shape is reduced to the fields that are functionally required.
• Documentation becomes explicit that entitlement identity is defined by Kind + Id.
• Users are no longer encouraged to treat display metadata as part of entitlement semantics.

Alternatives Considered

1. Keep DisplayName but document it as optional display-only metadata

This would be less disruptive, but it would keep the semantic ambiguity in the core model and continue to invite incorrect assumptions.

2. Keep DisplayName only in provider-specific outputs

This is acceptable only if it is fully outside the generic entitlement contract and clearly treated as provider-specific data rather than part of the normalized entitlement model.

3. Keep the model unchanged and only clean up examples

This does not solve the root problem. The misleading field would remain part of the core shape and would likely continue to leak into future implementations and docs.

Impact

• Does this affect existing workflows?
  • Yes. This is a breaking change for any workflow examples, provider outputs, tests, or downstream consumers that still expect DisplayName to exist on normalized entitlements.
• Any backward compatibility concerns?
  • Yes. Existing content that references DisplayName on entitlements must be updated. Because the project is still pre-1.0, this is the right time to make the model stricter and remove non-essential fields.

Additional Context

Definition of done:

• DisplayName is no longer part of the generic entitlement model.
• No shipped example, workflow, provider doc, or reference doc shows DisplayName as part of a normalized entitlement.
• Provider and mock-provider test data are updated accordingly.
• Any plan/export/debug documentation that previously showed entitlement DisplayName is updated.
• Repository-wide checks confirm there are no stale references to entitlement DisplayName in the generic model.

Test guidance:

• A dedicated test for "the field does not exist" is not required by itself.
• Tests should be added or updated only where they protect behavior, contracts, normalization, or serialization that previously included DisplayName.
• In other words: verify the contract and outputs that matter, not the absence of every removed property in isolation.
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Remove DisplayName from the generic entitlement model #268

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

Removes DisplayName from IdLE’s provider-agnostic entitlement identity model so entitlements are identified strictly by Kind + Id, reducing ambiguity in matching/lookup semantics across providers, steps, tests, examples, and docs.

Changes:

• Updated AD, Entra ID, and Mock providers to stop parsing/emitting DisplayName on normalized IdLE.Entitlement objects (Entra ID retains provider-specific Mail).
• Updated built-in entitlement steps (EnsureEntitlement + PruneEntitlements*) to stop parsing/passing DisplayName, and narrowed KeepPattern matching to Id only.
• Updated tests, example workflows, and documentation/references to reflect the new entitlement shape.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Steps/Invoke-IdleStepPruneEntitlements.Tests.ps1	Removes DisplayName from prune step test fixtures and keep entries.
tests/Steps/Invoke-IdleStepEnsureEntitlement.Tests.ps1	Updates EnsureEntitlement test input entitlement to Kind + Id only.
tests/ProviderContracts/EntitlementProvider.Contract.ps1	Updates entitlement contract fixture to omit DisplayName.
tests/Core/Test-IdleCondition.Tests.ps1	Updates entitlement objects used in Condition DSL tests to omit DisplayName.
tests/Core/Get-IdlePropertyValue.Tests.ps1	Replaces entitlement DisplayName extraction test with a Kind extraction test.
src/IdLE.Steps.Common/Public/Invoke-IdleStepPruneEntitlementsEnsureKeep.ps1	Updates help text to remove DisplayName from Keep entry shape.
src/IdLE.Steps.Common/Public/Invoke-IdleStepPruneEntitlements.ps1	Updates help text to remove DisplayName from Keep entry shape.
src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureEntitlement.ps1	Stops parsing/passing DisplayName when normalizing step entitlement input.
src/IdLE.Steps.Common/Private/Test-IdlePruneEntitlementShouldKeep.ps1	Removes KeepPattern matching against DisplayName (now Id only).
src/IdLE.Steps.Common/Private/ConvertTo-IdlePruneEntitlement.ps1	Removes DisplayName normalization for prune Keep entries.
src/IdLE.Provider.Mock/Public/New-IdleMockIdentityProvider.ps1	Removes DisplayName from mock entitlement seed data and normalization.
src/IdLE.Provider.EntraID/Public/New-IdleEntraIDIdentityProvider.ps1	Stops emitting/copying entitlement DisplayName; keeps provider-specific Mail in list output.
src/IdLE.Provider.EntraID/Private/ConvertTo-IdleEntraIDEntitlement.ps1	Updates normalization/help to drop DisplayName support (Mail remains).
src/IdLE.Provider.AD/Public/New-IdleADIdentityProvider.ps1	Stops emitting/copying entitlement DisplayName for AD groups.
src/IdLE.Provider.AD/Private/ConvertTo-IdleADEntitlement.ps1	Updates normalization/help to drop DisplayName support.
examples/workflows/templates/entraid-leaver.psd1	Removes DisplayName from leaver Keep entry example.
examples/workflows/templates/ad-leaver.psd1	Removes DisplayName from leaver Keep entry example.
docs/use/workflows/conditions.md	Removes DisplayName entitlement examples/paths; focuses on .Id member-access usage.
docs/reference/steps/step-prune-entitlements.md	Regenerated step reference to reflect updated Keep entry shape.
docs/reference/steps/step-prune-entitlements-ensure-keep.md	Regenerated step reference to reflect updated Keep entry shape.
docs/reference/steps/step-ensure-entitlement.md	Regenerated step reference to reflect updated entitlement input example.
docs/reference/providers/provider-mock.md	Updates provider reference to remove entitlement DisplayName field.
docs/reference/providers/provider-entraID.md	Updates provider reference to remove entitlement DisplayName field (Mail remains).
docs/reference/providers/provider-ad.md	Updates provider reference to remove entitlement DisplayName field.
docs/reference/capabilities.md	Updates entitlement list shape description to Kind + Id and notes provider-specific fields.

[github-actions]

Code Coverage Report

Overall Project	74.68%	🍏

There is no coverage information present for the Files changed

[blindzero]

@copilot make sure that PSSA warnings are all resolved.
On destructive measures (e.g. removing unused vars), consult before removing. If it is 100% sure that a parameter or var is not used in may be removed there. Make very very sure.
Especially check all documentations and instructions if it is made clear that common warnings are not occuring in the future.

[Copilot]

@copilot make sure that PSSA warnings are all resolved.
On destructive measures (e.g. removing unused vars), consult before removing. If it is 100% sure that a parameter or var is not used in may be r...

Done in commits 397198b and 7b62407. Fixed all PSSA warnings in the files this PR modified:

• PSUseDeclaredVarsMoreThanAssignments ($validationResult): replaced assignment with $null = — the return value was always discarded; the function is called for its throw-on-invalid side effect only.
• PSReviewUnusedParameter (Kind in both ResolveEntitlement methods): added $null = $Kind to explicitly acknowledge the contract parameter. The existing SuppressMessageAttribute was already there but PSSA does not honor it inside ScriptMethod scriptblocks — $null = $ParamName is the reliable fix for that context.
• PSAvoidUsingPlainTextForPassword ($PasswordGenerationSpecialCharSet): this is a false positive — the parameter holds allowed special characters for password generation, not a password value. Applied SuppressMessageAttribute at the function level with a clear justification. The parameter type is intentionally String and changing it to SecureString would be both incorrect and a breaking change.

No parameters or variables were removed. Repo-wide PSSA: 171 warnings (down from 175), 0 errors. All 841 tests pass.

Also added a PSSA guidance table to CONTRIBUTING.md covering $null =, SuppressMessageAttribute, and empty-catch patterns so contributors know the expected approach going forward.

[Copilot]

Pull request overview

This PR removes DisplayName from the generic IdLE.Entitlement model so entitlements are identified deterministically by stable identifiers (Kind + Id), and updates providers/steps/tests/examples/docs accordingly while cleaning up PSScriptAnalyzer (PSSA) warnings.

Changes:

• Removed DisplayName from normalized entitlement objects across built-in steps and provider implementations (AD/EntraID/Mock) and updated pruning/normalization helpers accordingly.
• Updated tests, examples, and documentation to reflect the reduced entitlement shape and the “Kind + Id” identity rule.
• Addressed PSSA issues (empty catch blocks, unused parameters, indentation/whitespace) and improved analyzer/tool robustness.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tools/Invoke-IdleScriptAnalyzer.ps1	Allows empty findings collections in summary output to prevent zero-results crashes.
tools/Generate-IdleStepReference.ps1	Adds verbose logging in catch and updates autogenerated entitlement example to omit DisplayName.
tests/Steps/Invoke-IdleStepPruneEntitlements.Tests.ps1	Updates prune/ensure-keep tests to use entitlements without DisplayName.
tests/Steps/Invoke-IdleStepEnsureEntitlement.Tests.ps1	Updates EnsureEntitlement step tests to omit DisplayName.
tests/ProviderContracts/EntitlementProvider.Contract.ps1	Updates provider contract test entitlement shape to Kind + Id only.
tests/Core/Test-IdleCondition.Tests.ps1	Updates condition DSL fixtures to entitlement objects without DisplayName.
tests/Core/Get-IdlePropertyValue.Tests.ps1	Updates member-access enumeration tests away from DisplayName examples.
src/IdLE.Steps.Common/Public/Invoke-IdleStepPruneEntitlementsEnsureKeep.ps1	Updates help text to remove DisplayName mention for Keep entries.
src/IdLE.Steps.Common/Public/Invoke-IdleStepPruneEntitlements.ps1	Updates help text to remove DisplayName mention for Keep entries.
src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureEntitlement.ps1	Removes DisplayName from entitlement normalization in the step and updates examples.
src/IdLE.Steps.Common/Private/Test-IdlePruneEntitlementShouldKeep.ps1	Removes DisplayName matching from KeepPattern logic (now Id-only).
src/IdLE.Steps.Common/Private/ConvertTo-IdlePruneEntitlement.ps1	Normalizes keep entries to Kind + Id (no DisplayName).
src/IdLE.Provider.Mock/Public/New-IdleMockIdentityProvider.ps1	Removes DisplayName from mock entitlements and normalization.
src/IdLE.Provider.EntraID/Public/New-IdleEntraIDIdentityProvider.ps1	Removes DisplayName from entitlement outputs and normalization/resolve behavior.
src/IdLE.Provider.EntraID/Private/ConvertTo-IdleEntraIDEntitlement.ps1	Updates converter docs/logic to no longer support DisplayName (keeps optional Mail).
src/IdLE.Provider.AD/Public/New-IdleADIdentityProvider.ps1	Removes DisplayName from AD entitlement outputs and resolves; fixes PSSA unused-var/unused-param warnings.
src/IdLE.Provider.AD/Private/New-IdleADAdapter.ps1	Adds/adjusts PSSA suppressions and fixes indentation/unused parameter warnings in adapter internals.
src/IdLE.Provider.AD/Private/ConvertTo-IdleADEntitlement.ps1	Updates converter docs/logic to remove DisplayName support.
src/IdLE.Core/Private/Resolve-IdleTemplateString.ps1	Adds PSSA suppression for nested-scriptblock parameter usage.
examples/workflows/templates/entraid-leaver.psd1	Removes DisplayName from entitlement keep entries in example workflow.
examples/workflows/templates/ad-leaver.psd1	Removes DisplayName from entitlement keep entries in example workflow.
docs/use/workflows/conditions.md	Removes DisplayName references from conditions/member-access guidance and examples.
docs/reference/steps/step-prune-entitlements.md	Updates generated step reference to remove DisplayName mention.
docs/reference/steps/step-prune-entitlements-ensure-keep.md	Updates generated step reference to remove DisplayName mention.
docs/reference/steps/step-ensure-entitlement.md	Updates generated step reference example to omit DisplayName.
docs/reference/providers/provider-mock.md	Removes DisplayName from documented normalized entitlement shape.
docs/reference/providers/provider-entraID.md	Removes DisplayName from documented output shape (retains provider-specific fields like Mail).
docs/reference/providers/provider-ad.md	Removes DisplayName from documented output shape.
docs/reference/capabilities.md	Updates entitlement list capability documentation to reflect Kind + Id core plus metadata/provider-specific fields.
CONTRIBUTING.md	Adds explicit PSSA remediation guidance patterns for contributors.