Skip to content

0.3.x-DiffReviewTools.md

Latest commit

 

History

History
43 lines (35 loc) · 3.44 KB

0.3.x-DiffReviewTools.md

File metadata and controls

43 lines (35 loc) · 3.44 KB
Raw

Diff and review tools (Feature Draft)

Status: Draft
Updated: 2026-05-20
Owner: Core
Purpose: Draft for visual review of content, schema, import, resolver, and operational changes before apply or publish.

Overview

  • Defines reusable diff/review tooling for drafts, versions, imports, generated changes, schema edits, menu edits, and operational plans.
  • Covers structured JSON diffs, Markdown diffs, rendered-preview diffs, resolver-output diffs, and large-payload handling.
  • Depends on error handling, editor experience, draft/publish workflow, import/export, operational admin workflows, and system UI.
  • Keeps review UX consistent across features instead of each workflow inventing its own comparison view.

Outline

Many CMS workflows need review before apply: publishing a draft, accepting generated content, applying an import, changing a schema, moving navigation items, restoring a backup, or updating modules. A shared diff/review toolkit makes these decisions safer and easier to understand.

The first implementation should support structured and textual comparisons without overbuilding. JSON-like payloads can use structured path diffs, Markdown can use rendered or line-based diffs, and resolver-aware views can show both stored tokens and resolved output when that helps the editor understand impact.

The first structured diff model should follow the practical shape already proven in the old resolver workflow: compare structured payloads by path and show which value changed in which field. This can start as a small internal formatter around immutable/versioned payloads instead of introducing a large diff dependency too early.

Technical Specifications

  • Provide a diff service boundary for structured payloads, Markdown/text, metadata, and rendered previews.
  • Start structured diffs with path-based value changes that show field path, previous value, new value, and operation type.
  • Support inline and side-by-side display modes where practical.
  • Highlight added, removed, changed, moved, and unchanged-but-contextual sections.
  • Support large payload handling through collapsing, chunking, truncation warnings, or async computation.
  • Integrate with draft/publish commit review, import dry-runs, schema version review, navigation publishing, resolver output preview, and operational action plans.
  • Cache expensive diff results only when inputs are immutable or versioned.
  • Keep diff output permission-aware and avoid leaking restricted fields or metadata.
  • Allow modules to add formatters through documented tagged services.

Testing & Validation

  • Test structured diffs for added, removed, changed, and moved values.
  • Test path-based structured diffs show exactly which field value changed.
  • Test Markdown/text diffs with large and localized payloads.
  • Test resolver-aware diffs once resolver output exists.
  • Test permission redaction for restricted fields.
  • Test import and draft review screens consume the shared diff output.

Implementation Notes

  • Decision recorded: Diff/review should be a shared toolkit used by editor, import/export, schema changes, navigation, and operational workflows.
  • Decision recorded: Resolver-aware review should show stored dynamic tokens separately from resolved output where useful.
  • Decision recorded: Start structured diffs with a small internal path-based formatter around immutable/versioned payloads, then revisit external libraries only if the first model proves insufficient.