Guided Tour & Diff Viewer
Relevant source files
The following files were used as context for generating this wiki page:
The Guided Tour and Diff Viewer represent the primary interface for consuming machine-generated code reviews. Instead of a flat list of file changes, Marginalia organizes findings and code into a narrative structure called a "tour." The system groups related files and findings into chapters to explain the intent and impact of changes chronologically or logically.
This system provides a high-density, technical environment where developers can verify AI-generated findings against the actual source code. It integrates live diffs, discussion threads from GitLab, and inline comment capabilities to facilitate efficient merge request (MR) triaging.
Sources: skills/marginalia-review/SKILL.md:58-69, studio/src/components/ReviewReader.tsx:66-70
Architecture and Component Hierarchy
The review reading experience follows a strict component hierarchy. The ReviewReader acts as the orchestrator, determining whether to render a guided tour based on the presence of tour data in the review shape.
The diagram shows the component flow from the top-level ReviewReader down to individual diff lines and findings.
Component Roles
| Component | Responsibility |
|---|---|
ReviewReader | Orchestrates high-level layout, manages submission states, and handles version history selection. |
ReviewTour | Manages the current "stop" index and coordinates the narrative flow with keyboard and UI navigation. |
DiffPane | Fetches and renders code diffs for specific files associated with a tour stop. |
FindingsPanel | Displays actionable items (critical/important issues) specific to the current context. |
ReviewSkeleton | Renders a "shimmering" UI placeholder while tour data and diffs are loading. |
Sources: studio/src/components/ReviewReader.tsx:50-70, studio/src/components/ReviewTour.tsx:36-60, studio/src/components/ReviewSkeleton.tsx:9-35
Tour Navigation and Logic
The tour decomposes a complex MR into a list of chapters. Each chapter, or TourStop, encapsulates a specific idea or logical change.
Stop Structure
A TourStop includes:
- ID & Title: Unique identifier and a human-readable name for the logical change.
- Summary: A plain-text explanation of the "what" and "why."
- Files: A list of repo-relative paths relevant to this specific stop.
- Finding IDs: Links to findings that belong specifically to this chapter.
- Supporting Flag: Indicates if the stop covers secondary material like tests or generated files.
Sources: studio/src/lib/api.ts:58-66, skills/marginalia-review/SKILL.md:65-71
Navigation Mechanisms
Users navigate the tour using:
- Visual Indicators: A progress bar at the top of the tour section allows direct clicking of specific stops.
- Button Controls: "Previous stop" and "Next stop" buttons.
- Keyboard Shortcuts: The
ArrowRightkey advances the tour, whileArrowLeftreturns to the previous stop. Shortcuts are automatically disabled when focus is inside inputs or textareas.
Sources: studio/src/components/ReviewTour.tsx:64-74, studio/src/components/ReviewTour.tsx:93-100
Diff Viewer Implementation
The DiffPane component renders the source code changes associated with the current tour stop. It utilizes a custom hook, useMrDiff, to fetch and process diff data.
Diff Scopes
The viewer supports two specific scopes via the ScopeToggle component:
- Full: Displays the MR state as it was when the review was originally generated.
- Since: Shows changes pushed to the MR after the review was created, allowing developers to see if issues were addressed.
Sources: studio/src/components/DiffPane.tsx:13-22, studio/src/components/ReviewTour.tsx:60-61
This sequence illustrates how navigation triggers data fetching for the code viewer.
Finding Anchors and Discussions
Findings are anchored directly to the code. If a finding includes a path and line, the DiffFileView renders that finding inline within the code diff. This allows developers to see the AI's comment in the exact context of the problematic code.
The system also integrates threads (existing GitLab discussions). These are shown alongside findings to provide full context of human and machine feedback.
Sources: studio/src/components/DiffPane.tsx:50-58, studio/src/lib/api.ts:101-109, studio/src/lib/links.tsx:55-63
Technical Data Models
The following data structures facilitate the tour and diff integration:
| Interface | Field | Type | Description |
|---|---|---|---|
Finding | comment | string | null | The text ready to be posted as a GitLab comment. |
Finding | severity | enum | critical, important, suggestion, or info. |
DiffFile | status | enum | added, deleted, renamed, or modified. |
DiffLine | t | enum | Line type: hunk, add, del, or ctx (context). |
Sources: studio/src/lib/api.ts:77-109
Linking Logic
The links.tsx utility handles the generation of GitLab URLs. It uses a SHA-1 hash of the file path to generate GitLab-compatible anchors for diffs.
- MR Refs: Formatted as
!iid. - File Refs: Formatted as
path/to/file:line.
Sources: studio/src/lib/links.tsx:20-53
Summary
The Guided Tour & Diff Viewer transforms static markdown reviews into an interactive, context-aware auditing tool. By grouping files into narrative stops and anchoring findings directly to code diffs, it reduces the cognitive load required to verify AI-generated feedback. The integration of scope toggling ("Full" vs "Since") ensures that the reviewer always understands the relationship between the machine's findings and the current state of the branch.