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
233 lines
20 KiB
Markdown
233 lines
20 KiB
Markdown
# Tasks: GUID Context Resolver & Human-Readable Reference Presentation (132)
|
|
|
|
**Input**: Design documents from `specs/132-guid-context-resolver/` (`spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`)
|
|
**Prerequisites**: `specs/132-guid-context-resolver/plan.md` (required), `specs/132-guid-context-resolver/spec.md` (required for user stories)
|
|
|
|
**Tests**: REQUIRED (Pest) for all runtime behavior changes in this repo.
|
|
**Operations**: No new `OperationRun` flow is introduced; this feature reuses existing operational records strictly as references and canonical destinations.
|
|
**RBAC**: Preserve workspace and tenant isolation, deny-as-not-found 404 for non-members, 403 for in-scope members missing capability, and capability-registry usage only for reference linkability.
|
|
**Filament UI**: This feature extends existing Filament resource and page surfaces only; keep inspect affordances explicit, visible row actions capped, and read-only detail rendering inside structured infolist or related-context sections.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Reconfirm the exact target surfaces, shared helpers, and test neighborhoods before introducing the common reference layer.
|
|
|
|
- [X] T001 Audit current reference-heavy seams in `app/Support/Navigation/RelatedNavigationResolver.php`, `app/Support/Navigation/CrossResourceNavigationMatrix.php`, `resources/views/filament/infolists/entries/related-context.blade.php`, `app/Support/OperationRunLinks.php`, and `app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php`
|
|
- [X] T002 [P] Audit current local lookup, label, and badge sources in `app/Services/Directory/EntraGroupLabelResolver.php`, `app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php`, `app/Services/Baselines/SnapshotRendering/RenderedSnapshotItem.php`, `app/Support/Badges/BadgeCatalog.php`, and `app/Support/Badges/BadgeRenderer.php`
|
|
- [X] T003 [P] Audit current reference-related and tenant-context test neighborhoods in `tests/Feature/PolicyVersionViewAssignmentsTest.php`, `tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php`, `tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php`, `tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php`, and `tests/Feature/Rbac/`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Build the shared reference contracts, registry, adapters, and renderers that every user story depends on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T004 Create shared reference value objects in `app/Support/References/ReferenceDescriptor.php`, `app/Support/References/ResolvedReference.php`, `app/Support/References/ReferenceLinkTarget.php`, `app/Support/References/ReferenceTechnicalDetail.php`, `app/Support/References/ReferencePresentationVariant.php`, and `app/Support/References/ReferenceResolutionState.php`
|
|
- [X] T005 Create resolver contracts and registry in `app/Support/References/Contracts/ReferenceResolver.php`, `app/Support/References/ReferenceResolverRegistry.php`, and `app/Support/References/Resolvers/FallbackReferenceResolver.php`
|
|
- [X] T006 Wire the shared reference layer into existing support seams in `app/Providers/AppServiceProvider.php`, `app/Support/Navigation/RelatedNavigationResolver.php`, and `app/Support/Navigation/RelatedContextEntry.php`
|
|
- [X] T007 [P] Create shared type and state presentation helpers backed by `app/Support/Badges/BadgeCatalog.php` and `app/Support/Badges/BadgeRenderer.php` in `app/Support/References/ReferenceTypeLabelCatalog.php` and `app/Support/References/ReferenceStatePresenter.php`
|
|
- [X] T008 [P] Create reusable reference renderers in `resources/views/filament/infolists/entries/resolved-reference-detail.blade.php`, `resources/views/filament/infolists/entries/resolved-reference-compact.blade.php`, and `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T009 [P] Add foundational unit coverage in `tests/Unit/Support/References/ReferenceResolverRegistryTest.php` and `tests/Unit/Support/References/ResolvedReferenceTest.php`
|
|
- [X] T010 [P] Add adapter, rendering, badge-mapping, and domain-copy smoke coverage in `tests/Feature/Filament/ResolvedReferenceRenderingSmokeTest.php`, `tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php`, and `tests/Unit/Support/References/ReferenceStateBadgeMappingTest.php`
|
|
|
|
**Checkpoint**: The repo has one shared reference contract, resolver registry, and rendering seam that all in-scope surfaces can consume consistently.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Read referenced objects without decoding IDs (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Operators can read internal model-backed references as names and context first across the highest-value surfaces instead of decoding GUIDs manually.
|
|
|
|
**Independent Test**: Open a finding, baseline snapshot, operation run, and backup set with supported internal references and verify the UI renders label-first references with contextual type and secondary technical IDs.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T011 [P] [US1] Add unit coverage for core model-backed resolvers in `tests/Unit/Support/References/ModelBackedReferenceResolverTest.php`
|
|
- [X] T012 [P] [US1] Add finding and baseline-snapshot feature coverage in `tests/Feature/Filament/FindingResolvedReferencePresentationTest.php` and `tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php`
|
|
- [X] T013 [P] [US1] Add operation-run and backup-set feature coverage in `tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php` and `tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T014 [US1] Implement model-backed resolvers in `app/Support/References/Resolvers/PolicyReferenceResolver.php`, `app/Support/References/Resolvers/PolicyVersionReferenceResolver.php`, `app/Support/References/Resolvers/BaselineProfileReferenceResolver.php`, `app/Support/References/Resolvers/BaselineSnapshotReferenceResolver.php`, `app/Support/References/Resolvers/OperationRunReferenceResolver.php`, and `app/Support/References/Resolvers/BackupSetReferenceResolver.php`
|
|
- [X] T015 [US1] Adapt internal reference descriptors and mappings in `app/Support/Navigation/CrossResourceNavigationMatrix.php` and `app/Support/Navigation/RelatedNavigationResolver.php`
|
|
- [X] T016 [US1] Refactor finding and operation-run detail surfaces to render resolved references in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T017 [US1] Refactor baseline-snapshot and backup-set surfaces to render resolved references in `app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php` and `app/Filament/Resources/BackupSetResource.php`
|
|
|
|
**Checkpoint**: User Story 1 is complete when the primary internal references on the target governance and operations screens are no longer GUID-first.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Understand degraded references safely (Priority: P1)
|
|
|
|
**Goal**: Operators can distinguish resolved, partial, missing, inaccessible, and limited-context provider-backed references without losing the underlying evidence.
|
|
|
|
**Independent Test**: Render provider-backed and assignment-like references in resolved, partial, unresolved, missing, and inaccessible states and verify each state remains visible, distinct, and non-misleading.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T018 [P] [US2] Add degraded-state and shared badge-vocabulary unit coverage in `tests/Unit/Support/References/ReferenceResolutionStateTest.php`, `tests/Unit/Support/References/UnsupportedReferenceResolverTest.php`, and `tests/Unit/Support/References/ReferenceStateBadgeMappingTest.php`
|
|
- [X] T019 [P] [US2] Add provider-backed group and role reference coverage in `tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php` and `tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php`
|
|
- [ ] T020 [P] [US2] Add degraded-state assignment and evidence coverage in `tests/Feature/PolicyVersionViewAssignmentsTest.php`, `tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php`, `tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php`, and `tests/Feature/Filament/BaselineTenantAssignmentsResolvedReferencePresentationTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T021 [US2] Implement provider-backed and governance resolvers in `app/Support/References/Resolvers/EntraGroupReferenceResolver.php`, `app/Support/References/Resolvers/EntraRoleDefinitionReferenceResolver.php`, `app/Support/References/Resolvers/PrincipalReferenceResolver.php`, and `app/Support/References/Resolvers/AssignmentTargetReferenceResolver.php`
|
|
- [X] T022 [US2] Refactor local group-label enrichment into structured resolution support in `app/Services/Directory/EntraGroupLabelResolver.php` and `app/Support/References/Resolvers/EntraGroupReferenceResolver.php`
|
|
- [X] T023 [US2] Implement shared degraded-state presentation, shared badge-domain mapping, and secondary technical-detail handling in `app/Support/References/ReferenceStatePresenter.php`, `resources/views/filament/infolists/entries/resolved-reference-detail.blade.php`, and `resources/views/filament/infolists/entries/resolved-reference-compact.blade.php`
|
|
- [ ] T024 [US2] Upgrade GUID-heavy directory and assignment evidence surfaces in `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php`, `app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php`, and `app/Services/Baselines/SnapshotRendering/RenderedSnapshotItem.php`
|
|
|
|
**Checkpoint**: User Story 2 is complete when degraded references look intentionally different from fully resolved ones and still preserve technical evidence secondarily.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Navigate from references when allowed (Priority: P2)
|
|
|
|
**Goal**: Authorized operators can follow resolved references to canonical destinations, while unauthorized or non-actionable references remain informative but non-clickable.
|
|
|
|
**Independent Test**: Open supported references from in-scope screens and verify that only permitted references are actionable and that every actionable link resolves to the canonical destination for that object.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T025 [P] [US3] Add authorization-aware link generation unit coverage in `tests/Unit/Support/References/ReferenceLinkTargetTest.php` and `tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php`
|
|
- [X] T026 [P] [US3] Add clickable versus non-clickable RBAC coverage, including assignment-like relation-manager cases and tenant-context entry to canonical destinations, in `tests/Feature/Rbac/ResolvedReferenceAuthorizationTest.php`
|
|
- [X] T027 [P] [US3] Add canonical destination and tenant-context carryover coverage in `tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php`, `tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php`, and `tests/Feature/Filament/TenantContextResolvedReferenceCarryoverTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [ ] T028 [US3] Add capability-aware canonical link generation in `app/Support/References/ReferenceLinkBuilder.php` and `app/Support/OperationRunLinks.php`
|
|
- [ ] T029 [US3] Refactor shared navigation mapping to consume canonical link targets in `app/Support/Navigation/RelatedNavigationResolver.php` and `app/Support/Navigation/CrossResourceNavigationMatrix.php`
|
|
- [ ] T030 [US3] Upgrade policy-version and finding row/detail actions to use resolved reference links while preserving explicit inspect affordances and row-action limits in `app/Filament/Resources/PolicyVersionResource.php` and `app/Filament/Resources/FindingResource.php`
|
|
- [ ] T031 [US3] Upgrade operation-run, baseline-snapshot, and baseline tenant assignment contextual links to use shared canonical destinations while keeping documented action-surface exemptions current and preserving tenant-context filters, badges, or source-context metadata on canonical destinations in `app/Filament/Resources/OperationRunResource.php`, `app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php`, `app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php`, and `app/Support/Navigation/CanonicalNavigationContext.php`
|
|
|
|
**Checkpoint**: User Story 3 is complete when canonical linking is role-aware, predictable, and never ambiguous about clickability.
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Extend the same pattern to future surfaces (Priority: P3)
|
|
|
|
**Goal**: The product can add new reference classes and new reference-heavy surfaces without reintroducing page-specific formatting logic.
|
|
|
|
**Independent Test**: Register an unsupported or future reference class through the shared layer and verify the page degrades safely without rewriting existing target templates.
|
|
|
|
### Tests for User Story 4
|
|
|
|
- [X] T032 [P] [US4] Add extensibility and unsupported-class regression coverage in `tests/Unit/Support/References/ReferenceResolverRegistryExtensibilityTest.php` and `tests/Feature/Filament/ResolvedReferenceUnsupportedClassTest.php`
|
|
- [ ] T033 [P] [US4] Add regression coverage preventing GUID-first rendering from returning in `tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`, `tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php`, and `tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php`
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [X] T034 [US4] Add reusable reference registration seams in `app/Support/References/ReferenceClass.php`, `app/Support/References/ReferenceResolverRegistry.php`, and `app/Providers/AppServiceProvider.php`
|
|
- [ ] T035 [US4] Replace remaining page-specific GUID formatting branches, refresh action-surface declarations, and normalize domain-consistent operator copy across labels, helper text, link text, empty states, and degraded-state copy on touched Filament surfaces in `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php`, and `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T036 [US4] Add reusable compact/detail presentation adapters for future surfaces in `app/Support/References/ResolvedReferencePresenter.php` and `app/Support/References/RelatedContextReferenceAdapter.php`
|
|
|
|
**Checkpoint**: User Story 4 is complete when a new supported reference class can be added through the shared layer without touching every existing target surface.
|
|
|
|
---
|
|
|
|
## Phase 7: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final verification, formatting, and cross-surface cleanup after all user stories are implemented.
|
|
|
|
- [X] T037 [P] Run focused Pest verification from `specs/132-guid-context-resolver/quickstart.md`
|
|
- [X] T038 [P] Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [ ] T039 Validate the manual QA scenarios, tenant-context carryover behavior, domain-consistent operator copy, and rollout boundary from `specs/132-guid-context-resolver/quickstart.md`, confirming the named in-scope surfaces are migrated while out-of-scope dashboards and later summary views are explicitly deferred
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup; blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
|
|
- **User Story 2 (Phase 4)**: Depends on Foundational completion and can proceed independently of US1 once the shared layer exists.
|
|
- **User Story 3 (Phase 5)**: Depends on Foundational completion and benefits from US1 and US2 because the same resolved-reference contracts and degraded-state vocabulary will already be in place.
|
|
- **User Story 4 (Phase 6)**: Depends on Foundational completion and should land after the main surfaces prove the shared pattern works.
|
|
- **Polish (Phase 7)**: Depends on all desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: First MVP slice; no dependency on other user stories.
|
|
- **User Story 2 (P1)**: Independent after Foundational, though it reuses the same registry, renderers, and target surfaces established by US1.
|
|
- **User Story 3 (P2)**: Independent after Foundational, but gains efficiency once US1 and US2 establish the core reference payloads and degraded-state rules.
|
|
- **User Story 4 (P3)**: Independent after Foundational but should follow the main surface rollout so extensibility is shaped by proven behavior rather than theory.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests should be added before or alongside implementation and must fail before the story is considered complete.
|
|
- Resolver registration and value-object work should land before surface wiring.
|
|
- Shared rendering and degraded-state presentation should be complete before final linkability or row-action cleanup.
|
|
- Authorization-aware behavior must be enforced before story verification is treated as complete.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- Setup tasks `T002` and `T003` can run in parallel.
|
|
- In Foundational, `T007`, `T008`, `T009`, and `T010` can run in parallel after the core file layout from `T004` through `T006` is agreed.
|
|
- In US1, `T011`, `T012`, and `T013` can run in parallel.
|
|
- In US2, `T018`, `T019`, and `T020` can run in parallel.
|
|
- In US3, `T025`, `T026`, and `T027` can run in parallel.
|
|
- In US4, `T032` and `T033` can run in parallel.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch US1 test work in parallel:
|
|
T011 tests/Unit/Support/References/ModelBackedReferenceResolverTest.php
|
|
T012 tests/Feature/Filament/FindingResolvedReferencePresentationTest.php + tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php
|
|
T013 tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php + tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch US2 test work in parallel:
|
|
T018 tests/Unit/Support/References/ReferenceResolutionStateTest.php + tests/Unit/Support/References/UnsupportedReferenceResolverTest.php
|
|
T019 tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php + tests/Feature/Filament/TenantRoleDefinitionsSelectorDbOnlyTest.php
|
|
T020 tests/Feature/PolicyVersionViewAssignmentsTest.php + tests/Feature/Drift/DriftFindingDetailShowsAssignmentsDiffTest.php + tests/Feature/Filament/BaselineSnapshotRbacRoleDefinitionsTest.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch US3 test work in parallel:
|
|
T025 tests/Unit/Support/References/ReferenceLinkTargetTest.php + tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php
|
|
T026 tests/Feature/Rbac/ResolvedReferenceAuthorizationTest.php
|
|
T027 tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php + tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Validate the label-first internal-reference behavior on findings, snapshots, runs, and backup sets before expanding further.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Ship US1 to eliminate GUID-first rendering for the primary internal references.
|
|
2. Add US2 to make degraded and provider-backed references explicit and safe.
|
|
3. Add US3 to make canonical linking capability-aware and predictable.
|
|
4. Add US4 to lock in extensibility and prevent a return to page-specific formatting logic.
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- MVP = Phases 1 through 3, then run the focused verification from `specs/132-guid-context-resolver/quickstart.md`.
|
|
|
|
---
|
|
|
|
## Format Validation
|
|
|
|
- Every task follows the checklist format `- [ ] T### [P?] [US?] Description with file path`.
|
|
- Setup, Foundational, and Polish phases intentionally omit story labels.
|
|
- User story phases use `[US1]`, `[US2]`, `[US3]`, and `[US4]` labels.
|
|
- Parallel markers are used only where tasks can proceed independently without conflicting incomplete prerequisites.
|