ahmido
8ee1174c8d
## 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
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# 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
|
|
|
|
1. Work on branch `132-guid-context-resolver`.
|
|
2. Ensure Sail is running:
|
|
|
|
```bash
|
|
vendor/bin/sail up -d
|
|
```
|
|
|
|
3. 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
|
|
|
|
1. Add the shared reference contracts under `app/Support/References/`.
|
|
2. Implement the resolver registry and fallback resolver.
|
|
3. Add core internal resolvers for policy, policy version, baseline profile, baseline snapshot, operation run, and backup set.
|
|
4. Add governance and provider-backed resolvers for role definitions, groups, principals, and assignment-like targets that are already surfaced.
|
|
5. Upgrade the shared renderers with compact and detailed variants while keeping technical IDs secondary.
|
|
6. Refactor target surfaces to consume resolved references instead of ad hoc label or GUID formatting.
|
|
7. 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.
|
|
8. Normalize operator-facing copy across labels, helper text, link labels, empty states, and degraded-state messaging.
|
|
9. Add unit and feature tests, then run focused verification.
|
|
|
|
## Verification
|
|
|
|
Run focused tests for the new support layer and target surfaces:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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. |