ahmido 8ee1174c8d feat: add resolved reference presentation layer (#161 )

## Summary
- add the shared resolved-reference foundation with registry, resolvers, presenters, and badge semantics
- refactor related context, assignment evidence, and policy-version assignment rendering toward label-first reference presentation
- add Spec 132 artifacts and focused Pest coverage for reference resolution, degraded states, canonical linking, and tenant-context carryover

## Verification
- `vendor/bin/sail bin pint --dirty --format agent`
- focused Pest verification was marked complete in the task artifact

## Notes
- this PR is opened from the current session branch
- `specs/132-guid-context-resolver/tasks.md` reflects in-progress completion state for the implemented tasks

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #161

2026-03-10 18:52:52 +00:00

2.9 KiB

Raw Blame History

Quickstart: GUID Context Resolver & Human-Readable Reference Presentation

Goal

Implement a shared reference-resolution and rendering layer that makes supported references display as label-first, context-second, and technical-ID-last across findings, snapshots, operation runs, assignments, and related-context sections.

Preconditions

Work on branch 132-guid-context-resolver.
Ensure Sail is running:

vendor/bin/sail up -d

Review the current shared navigation and rendering entry points:
- app/Support/Navigation/RelatedNavigationResolver.php
- app/Support/Navigation/CrossResourceNavigationMatrix.php
- app/Support/Navigation/RelatedContextEntry.php
- resources/views/filament/infolists/entries/related-context.blade.php
- app/Support/OperationRunLinks.php
- app/Services/Directory/EntraGroupLabelResolver.php

Implementation Sequence

Add the shared reference contracts under app/Support/References/.
Implement the resolver registry and fallback resolver.
Add core internal resolvers for policy, policy version, baseline profile, baseline snapshot, operation run, and backup set.
Add governance and provider-backed resolvers for role definitions, groups, principals, and assignment-like targets that are already surfaced.
Upgrade the shared renderers with compact and detailed variants while keeping technical IDs secondary.
Refactor target surfaces to consume resolved references instead of ad hoc label or GUID formatting.
Preserve originating tenant meaning when a tenant-context source links to a canonical workspace destination by carrying visible filters, context badges, or source-context metadata where relevant.
Normalize operator-facing copy across labels, helper text, link labels, empty states, and degraded-state messaging.
Add unit and feature tests, then run focused verification.

Verification

Run focused tests for the new support layer and target surfaces:

vendor/bin/sail artisan test --compact --filter=Reference
vendor/bin/sail artisan test --compact --filter=Finding
vendor/bin/sail artisan test --compact --filter=BaselineSnapshot
vendor/bin/sail artisan test --compact --filter=OperationRun

Run formatting after code changes:

vendor/bin/sail bin pint --dirty --format agent

Expected Outcome

Supported references no longer render GUIDs as primary visible text on target surfaces.
Unresolved, missing, partially resolved, and inaccessible states are visibly distinct.
Canonical links remain authorization-aware and non-ambiguous.
Canonical workspace destinations reached from tenant-context sources preserve visible tenant meaning where relevant.
Operator-facing copy remains domain-consistent across labels, helper text, link text, empty states, and degraded-state messaging.
Existing related-context consumers and future surfaces can reuse the same shared reference semantics.

2.9 KiB Raw Blame History