Ahmed Darrazi 0415e9af88 feat: add resolved reference presentation layer

2026-03-10 19:51:41 +01:00

20 KiB

Raw Blame History

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.

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
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
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.

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
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
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
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
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
T009 [P] Add foundational unit coverage in tests/Unit/Support/References/ReferenceResolverRegistryTest.php and tests/Unit/Support/References/ResolvedReferenceTest.php
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

T011 [P] [US1] Add unit coverage for core model-backed resolvers in tests/Unit/Support/References/ModelBackedReferenceResolverTest.php
T012 [P] [US1] Add finding and baseline-snapshot feature coverage in tests/Feature/Filament/FindingResolvedReferencePresentationTest.php and tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php
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

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
T015 [US1] Adapt internal reference descriptors and mappings in app/Support/Navigation/CrossResourceNavigationMatrix.php and app/Support/Navigation/RelatedNavigationResolver.php
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
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

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
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

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
T022 [US2] Refactor local group-label enrichment into structured resolution support in app/Services/Directory/EntraGroupLabelResolver.php and app/Support/References/Resolvers/EntraGroupReferenceResolver.php
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

T025 [P] [US3] Add authorization-aware link generation unit coverage in tests/Unit/Support/References/ReferenceLinkTargetTest.php and tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php
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
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

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

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
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.

T037 [P] Run focused Pest verification from specs/132-guid-context-resolver/quickstart.md
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

# 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

# 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

# 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)

Complete Phase 1: Setup.
Complete Phase 2: Foundational.
Complete Phase 3: User Story 1.
Validate the label-first internal-reference behavior on findings, snapshots, runs, and backup sets before expanding further.

Incremental Delivery

Ship US1 to eliminate GUID-first rendering for the primary internal references.
Add US2 to make degraded and provider-backed references explicit and safe.
Add US3 to make canonical linking capability-aware and predictable.
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.

20 KiB Raw Blame History