Report Data Format
Relevant source files
The following files were used as context for generating this wiki page:
The Marginalia Report Data Format defines how the bot collects, parses, and represents code review findings generated by Claude Code commands. The system supports two primary input methods: a structured JSON findings file and a formatted Markdown report.
The bot normalizes every report into a standard internal shape, enabling the studio to provide a consistent interface for reading reviews, counting issues by severity, and posting comments back to GitLab.
Sources: README.md:31-41, studio/public/openapi.yaml:286-296
Data Collection and Normalization
The bot executes review commands and attempts to collect a report in a specific order of preference. It first looks for a .marginalia-report.md file in the worktree, then searches for a specific marker block in standard output (stdout), and finally falls back to the raw final message if it exceeds 200 characters.
Sources: README.md:23-29, test/fixtures/skills/marker-block/stdout.txt:1-5
The Normalization Flow
The following diagram illustrates how the bot processes various input formats into a unified ReviewShape.
The bot converts raw command output into a structured data model used by the React studio.
Sources: README.md:31-48, studio/public/openapi.yaml:286-296
Structured JSON Format (.marginalia-findings.json)
The structured JSON format is the recommended way for commands to deliver reviews. It allows for precise control over finding IDs and ensures stability across re-runs.
Finding Data Model
| Field | Type | Description |
|---|---|---|
id | string | Stable ID based on file and point, used for tracking posted state. |
severity | string | One of: critical, important, suggestion, info. |
title | string | Short description of the issue. |
path | string | Repo-relative file path for the finding. |
line | integer | Line number in the new version of the file. |
body | string | Detailed technical explanation of the finding. |
comment | string | The ready-to-post comment for GitLab. |
Sources: studio/public/openapi.yaml:274-285, README.md:37-41
Markdown Parsing Logic
When a structured JSON file is absent, the bot parses the Markdown report to extract metadata and findings. It uses specific regex patterns and heading structures to identify critical components.
Metadata Extraction
The bot searches for a metadata line containing branch, ticket, and MR information.
const META_LINE = /^[ \t]*\*\*Branch:\*\*[ \t]*(.*?)[ \t]*\|[ \t]*\*\*Ticket:\*\*[ \t]*(.*?)[ \t]*\|[ \t]*\*\*MR:\*\*[ \t]*(.*?)[ \t]*$\n?/m;
Sources: studio/src/lib/reviewSections.ts:46-47
Section Ranking and Sorting
The studio categorizes and ranks sections based on their titles to ensure a logical reading order.
| Title Pattern | Rank | Purpose |
|---|---|---|
summary | 0 | High-level goal of the MR. |
at a glance | 1 | Definition list (What/Why/Risk/Blocking). |
shape of the change | 2 | Overview of architectural changes. |
critical | 3 | Blocking bugs or security holes. |
important | 4 | Important logic issues or missing tests. |
suggestion | 5 | Optional improvements. |
Sources: studio/src/lib/reviewSections.ts:10-18, skills/marginalia-review/SKILL.md:43-52
Finding Extraction from Markdown
The bot identifies findings in Markdown by looking for bulleted lists under severity headings (e.g., ## Critical). A finding's anchor is derived from the first path:line pattern found in the bullet text. If a blockquote exists immediately under a bullet, it is treated as the comment to be posted to GitLab.
Sources: README.md:42-45, studio/src/components/ReviewMarkdown.tsx:16-32
Triage and Across-Layer Findings
Specialized formats exist for specific review scenarios, such as stacked merge requests.
Across-Layer Schema
For stacked MRs, findings include relationships between different layers of the stack.
- settled-later: An issue in the current layer is resolved in a higher layer.
- belongs-lower: Code in this layer should move to a supporting layer.
- assumes-upper: This layer depends on logic not yet merged.
Sources: studio/public/openapi.yaml:262-266, README.md:88-93
Triage Report Structure
Triage reports focus on peer comments and follow a specific section-based format:
- Original reviewer comment.
- Bot verdict (
RELEVANT,NOT RELEVANT, orWRONG). - Rationale and applied fix or drafted reply.
Sources: examples/commands/triage.md:7-9, README.md:111-118
Conclusion
The Report Data Format ensures that diverse review tools can integrate with the Marginalia Studio. By providing a fallback from structured JSON to parsed Markdown, the system maintains flexibility while enforcing a strict internal data model for consistent user experience and GitLab integration.