A REAL PULL REQUEST, EXPLAINED

See what a pull request with Proof looks like.

This is the quality of pull request evidence and review that Proof helps your team produce.

Below is a real Omarchy PR and its linked Proof evaluation. Follow the highlighted notes to see how the change, blast radius, tests, demonstrations, and open decisions form a reviewable evidence pack.

The original PR is always one click away. The notes are our guide to reading it.

THE ANNOTATED EXAMPLE

Fix menu JSONC parsing: commas in strings, array roots, inline comments #13968

Open at source checkbuger opened this pull request on 1 Oct 2026·3 commits·quattro
The real PR and its evidence Adapted from the original PR and its linked Proof record. Snapshot · 30 Oct 2026 Why this makes a better review Select a note to highlight its passage. Explanations follow each section. Tap one to highlight it.
buger commented on 1 Oct 2026 · edited
Author

Fixes #13250, fixes #13492, fixes #13493.

This replaces #13255, #13511 and #13512, which fixed these bugs one at a time and conflicted in menu-test.sh. Three commits on quattro 8b4eae6: the fix, a Unicode-whitespace follow-up, and a test for a case reported in the thread.

Note

Three menu-JSONC parsing bugs, fixed in one string-aware pass. The original shipped-menu fixture parses unchanged: the same 344 rows. The PR also supplies 200,000 generated comparisons against #13681.

What this changes

IssueWhat goes wrong on quattroAfter this PR
#13250A comma inside a string (, ] or , } in a label or action) is silently eaten.The string is kept intact.
#13492An array root turns into entries "0", "1", …An array root contributes no entries.
#13493One inline // comment makes the whole file fail to parse.Inline comments are handled; the file parses.
Unicode whitespace,
vertical tab,
form feed
Outside strings, these can make parsing fail unless the old comment regex consumes them. Quickshell already removes a BOM at the start of a file.Read as plain whitespace anywhere outside a string.

Swipe the table to compare all three columns

stripJsonc becomes one string-aware pass, and parseMenuJsonc returns no rows for an array root. The pass preserves the whitespace behavior the old comment regex provided and extends it between tokens. docs/menu.md states the rules.

How the new pass works

String contents are copied unchanged. Outside strings, // drops the rest of its line while preserving the line feed. A comma is dropped only when the next character after whitespace and line comments is } or ]. Other JavaScript whitespace is normalized to a plain space.

Reproduce each bug — one-liners from the repo root

Commas inside strings

node -e 'const m=require("./shell/plugins/menu/MenuModel.js"); console.log(m.parseMenuJsonc(`{"b":{"label":"x, ]y","action":"mv f{.bak,}"}}`).map(r => [r.label,r.action]))'

quattro: x ]y and mv f{.bak}.
This PR: x, ]y and mv f{.bak,}.

Array roots

node -e 'const m=require("./shell/plugins/menu/MenuModel.js"); console.log(m.parseMenuJsonc(`[{"label":"x"},{"label":"y"}]`).map(r => r.id))'

quattro: [ '0', '1' ]. This PR: [].

Inline comments

node -e 'const m=require("./shell/plugins/menu/MenuModel.js"); console.log(m.parseMenuJsonc(`{"a":{"label":"A"}} // note`).length)'

quattro: 0. This PR: 1.

A 42-second capture compares the shipped parser at 8b4eae6 with this branch at b2dae8db. It reads two files ending in a trailing comma and an inline // favorites comment. The old parser returns 0 rows for each; the changed parser returns 3.

menu-jsonc-comment-tail.mp442 seconds
Original audio and on-screen captions8b4eae6 → b2dae8db

Control: without the inline comment, the sample parses to 3 rows on both revisions. This demonstrates parser output at the recorded revisions.

What it could affect

The production changes are confined to stripJsonc and parseMenuJsonc in shell/plugins/menu/MenuModel.js. The original shipped-menu fixture parses to the same 344 rows, with identical row data. /* */ block comments stay unsupported.

Important

A trailing comma, then a // comment line, then } must keep parsing. The sample extension looks like that once its examples are uncommented. #13512 and #13681 break this shape; here the comma lookahead also skips comments.

Reproduce the trailing-comma-then-comment shape
node -e 'const m=require("./shell/plugins/menu/MenuModel.js"); console.log(m.parseMenuJsonc(`{\n  "a":{"label":"A"},\n  // "b":{"label":"B"},\n}`).length)'

quattro: 1. #13512 and #13681: 0. This PR: 1.

How to check it

Checks reported in the PR

  • test/shell.d/menu-test.sh gets 36 new assertions (127 → 163 ok).
  • The rewritten parser’s branches and conditions are exercised in both directions.
  • The shipped menu is unchanged: 344 rows, identical row data.
  • Every menu test still passes, as do the related PRs’ own menu-test files.
  • 200,000 generated comparisons against #13681 isolate the comma-lookahead difference.
  • Generated whitespace comparisons preserve the documents the original parser already reads correctly.
The 36 new assertions: 16 catch failures, 20 preserve behavior

16 fail on the original parser: commas in labels and actions, escaped-quote cases, array roots, inline comments, trailing-comma/comment combinations, and whitespace before the root.

20 preserve existing behavior: escaped backslashes, object roots, comment slashes inside strings, the shipped example, token separation, and whitespace handling.

The original 127-assertion suite and the new 163-assertion suite were independently replayed for this walkthrough on Linux / Node 24.22.1. All 36 added assertions pass at the PR head. The PR author’s environment is Linux / Node 26.

Run the menu tests and inspect the related PR checks
for f in $(grep -rlE 'MenuModel|parseMenuJsonc|stripJsonc|omarchy-menu\.jsonc|menu/Menu\.qml' test/shell.d); do
  bash "$f" >/dev/null 2>&1 && echo "ok   $f" || echo "FAIL $f"
done

The PR also reports that the menu-test files from #13255, #13511, #13512, #13681, #13305, and #6525 pass against this branch.

Inspect the 200,000-comparison workload and its limits

The published deterministic script produces 4,187 differing comparisons; disabling this PR’s comment-skipping lookahead produces 0. Our replay on 30 October 2026 reproduced those results.

The stream contains 855 distinct input strings, with 62,183 iterations rejected by both parsers. The iteration count does not represent 200,000 unique cases or exhaustive coverage.

Download the replay script · Pinned #13968 parser · Pinned #13681 parser · Inspect the verification record

Open points

#13681 fixes the same three issues, with differences in comma lookahead and whitespace handling. #13305 and #6525 touch the same lines, so whichever lands first makes the others conflict.

Related pull requests
PRWhat it covers
#13681 by AnPodThe same three issues, with the noted behavioral differences.
#13305 by Cid-oeThe comma-in-string issue on its own.
#6525 by itscallsshInline comments.

What I’m asking

A review of this as the single fix for #13250, #13492 and #13493.

Note

If the maintainer prefers #13681, the author offers to carry over the comma lookahead, whitespace branch, and their tests, and close this PR.

Proof connects this change to its requirements and verification record.

View evaluation
Proof evaluation · companion record
Linked evidence

The following excerpts come from the linked Proof audit. They are additional evidence, outside the upstream PR description.

The proposed behavior, made explicit

SW-REQ-260927-66FW Proposed requirement

At a comma: remove it only when it is outside a string and the next significant character is } or ]. The lookahead skips whitespace and // comments. A comma inside a string is data.

Formalized intent Always, at a comma
trailing_comma_dropped
  ⇔ (!comma_in_string & next_char_closes_json)
Explore the four cases

Drop the comma Outside a string, followed by a closing delimiter.

Inside a string?Closing delimiter next?Rule says
NoNoKeep
NoYesDrop
YesNoKeep
YesYesKeep

An illustration of the proposed rule, not a parser execution or a new test run.

The audit proposes this rule. A related test passing does not approve the requirement on the maintainer’s behalf.

Intent, impact, and checks in one record

Traced reach30 requirements — 6 linked to changed functions, 24 through whole-file traces.
Proposed intent7 audit-layer requirement updates — 5 text changes and 2 metadata changes. The other 23 requirements must keep holding.
Obligation checks62 recorded dispositions — 35 observed passing, 19 covered by more specific requirements, 4 accepted debt, 4 not applicable.
Behavior review135 recorded differences in 5 families — 124 relate to whitespace. The notes explain intended behavior; maintainers still decide.
Remaining questions and evidence limits
  • Runtime: Quickshell/QV4 behavior and performance parity remain unanswered in the recorded review.
  • Policy: previously invalid user extensions can now load. Whether they should override shipped entries needs a decision.
  • Coverage: six relevant tests lack recorded confirmation that they reach the changed code; call-level side-effect reporting is unavailable.
  • Skipped checks: 13 audit checks were skipped. This is separate from the recorded test report’s zero skipped tests.
  • Fixture scope: the later upstream fixture has 346 rows. Old and new parsers agree on each fixture: 344 on the original, 346 on the later one.
  • Freshness: the Proof baseline moved after the evaluation; a re-check is pending.
THE STANDARD TO TAKE WITH YOU

Your standards.
A clear human decision.

Proof prepares the evidence around the requirements and quality bar your team defines. The reviewer decides what to accept, what to change, and where more investigation is needed.

Bring a change to Proof
An example 25-minute review Human acceptance

Illustrative time budget, not a measured result for this PR. These checkboxes do not submit an approval.

ORIGINAL PROOF CAPTURE

Evidence record

Archived Proof evidence recordOpen the underlying record ↗