TenantAtlas/specs/141-shared-diff-presentation-foundation/research.md

Research: Shared Diff Presentation Foundation

Decision 1: Keep the foundation in a dedicated presentation support layer under app/Support/Diff

• Decision: Introduce the shared diff primitives in app/Support/Diff/ as presentation-only support classes: DiffRowStatus, DiffRow, DiffSummary, DiffPresenter, and ValueStringifier.
• Rationale: The repo already uses support-oriented layers for reusable UI and rendering concerns, while current diff behavior is fragmented across Blade templates and a few domain services. A support-layer location makes the new foundation easy to consume from Findings, PolicyVersion, RestoreRun, and future baseline/evidence screens without implying domain ownership or database coupling.
• Alternatives considered:
  • Put the foundation inside app/Services/Intune/: rejected because the consumers are broader than Intune policy versioning and restore preview flows.
  • Put the foundation inside one Filament resource: rejected because the feature is intentionally consumer-agnostic.
  • Build a generic diff engine package: rejected because the spec explicitly forbids a full generic diff framework.

Decision 2: Treat existing compare producers as inputs, not migration targets

• Decision: The foundation will adapt simple structured compare payloads from existing producers such as VersionDiff, RestoreDiffGenerator, and diff payloads already rendered in Findings and PolicyVersion surfaces, while leaving specialized normalized diff rendering out of scope for now.
• Rationale: Current compare outputs already vary: normalized-diff renders grouped dot-path changes with script-specific handling, RBAC diff uses side-by-side baseline/current cards, assignments and scope tags use custom section layouts, and restore preview/results wrap policy-level diff summaries. Forcing them into one canonical business payload now would add risk and block incremental adoption.
• Alternatives considered:
  • Rewrite all existing compare producers to emit one canonical format: rejected because it would expand the feature into a cross-domain refactor.
  • Limit the feature to one local consumer such as RBAC diff only: rejected because the product needs a reusable base for multiple upcoming compare surfaces.

Decision 3: Centralize state badge semantics through the existing badge catalog

• Decision: Map shared diff states and summary badges through the existing badge catalog pattern rather than hardcoding colors in new partials.
• Rationale: The repo already centralizes badge semantics via BadgeCatalog, BadgeDomain, and focused badge tests. Existing diff templates still inline success, danger, and warning decisions; this feature is the right place to stop that drift for the shared foundation. Centralizing diff-state badge semantics aligns with BADGE-001 and keeps future consumers consistent.
• Alternatives considered:
  • Inline state-to-color mappings in each partial: rejected because it recreates the current inconsistency problem.
  • Use Tailwind-only classes without a semantic mapping layer: rejected because the repo already standardizes status-like badges centrally.

Decision 4: Use composable Blade partials under resources/views/filament/partials/diff

• Decision: Build low-magic Blade partials for summary badges, generic row rendering by state, and inline list diff rendering under resources/views/filament/partials/diff/.
• Rationale: Current consumers already use ViewEntry and Blade partials as the main extension point. Adding composable partials fits existing Filament patterns, works inside infolists and custom page content, and avoids introducing a custom Filament field or entry framework before it is justified.
• Alternatives considered:
  • Introduce a custom Filament field/entry component framework now: rejected because the spec explicitly says to avoid that unless Blade composition proves insufficient later.
  • Create a single master diff page component: rejected because consumers vary between summary-first views, side-by-side views, and specialized normalized diffs.

Decision 5: Keep Blade presentational and move formatting/row shaping into PHP

• Decision: Put row-state classification, list-fragment preparation, and value stringification into PHP support classes, leaving Blade responsible only for rendering.
• Rationale: Existing templates duplicate stringification rules and state grouping logic. The new foundation exists to improve consistency and testability, so the plan shifts logic into unit-testable support classes while keeping the partial APIs simple.
• Alternatives considered:
  • Continue using per-template closures for formatting: rejected because it duplicates logic and weakens regression coverage.
  • Put all formatting in one presenter and no standalone stringifier: rejected because the spec requires value formatting to be reusable even without the row presenter.

Decision 6: Define a small internal contract rather than a new HTTP API

• Decision: Document the foundation contract as an internal OpenAPI-style schema with no new paths and component schemas describing presenter input, row output, summary counts, and inline list fragments.
• Rationale: The feature adds no routes, but SpecKit still expects a contract artifact. A pathless schema captures the internal handoff clearly for follow-up specs and keeps the feature aligned with its “no new routes” boundary.
• Alternatives considered:
  • Skip the contracts artifact entirely: rejected because the planning workflow expects one.
  • Invent a fake endpoint solely for the plan: rejected because it would contradict the specification.

Decision 7: Cover rendering behavior with focused Pest unit and view-level tests

• Decision: Add unit tests for enum, row, presenter, and stringifier behavior plus view-level tests that render the shared partials with representative fixtures and assert accessible state cues, summary counts, dark-mode-safe class presence, and inline list diff output.
• Rationale: The spec requires both PHP-layer determinism and reusable rendering safety. The repo already uses Pest heavily, including badge mapping tests and feature tests around Filament rendering. This keeps the foundation verifiable without a full browser workflow.
• Alternatives considered:
  • Rely on manual UI verification only: rejected because the foundation is intended for repeated reuse.
  • Add browser tests first: rejected because the behavior under test is mostly server-side presentation and Blade output.

Key integration observations

• app/Services/Intune/VersionDiff.php already produces simple added, removed, and changed buckets for normalized comparisons.
• app/Services/Intune/RestoreDiffGenerator.php already computes policy-level preview summaries and truncation metadata that a consumer can adapt into the shared presentation layer.
• resources/views/filament/infolists/entries/normalized-diff.blade.php contains substantial specialized logic including stringification, grouped rows, and script-aware diff handling; it should remain specialized in this feature.
• resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php, assignments-diff.blade.php, and scope-tags-diff.blade.php show three separate simple diff rendering patterns that are strong future adoption candidates.
• app/Support/Badges/BadgeCatalog.php and existing badge tests provide the canonical place to centralize diff state badge semantics.