M4.3: side-by-side diff viewer with next/previous change

vcs.showDiff {path?, staged?} (Mod+Alt+Shift+D) opens a "Diff: <name>"
tab in the editor area: @codemirror/merge (MIT, loaded lazily, 27 kB /
9.7 kB gzip), with the index (or HEAD for the staged view) read-only on
the left, line breaks normalised to LF, and the working copy on the right,
editable through its normal engine buffer. vcs.nextChange (Alt+Shift+])
and vcs.previousChange (Alt+Shift+[) move between chunks. Binary, too
large, failed and deleted files show a notice. Entry points: the Changes
window, a new project tree context menu (Open, Show Diff; right click or
Shift+F10) and the palette/menu. Colours come from the --lt-vcs-* tokens.
21 Vitest tests; parity docs updated (Git 6% -> 8%, est.).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-26 17:23:52 +01:00
parent 468b9928a7
commit 8360ffc2e2
23 changed files with 1836 additions and 24 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4) · **Last updated:** 2026-10-25
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4), diff viewer (M4.3) · **Last updated:** 2026-10-26
## Overview
@ -609,6 +609,19 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **Measured** (debug build with the bundled UI, Windows 11, git 2.47.1, control port 7944, a temp repository with the owner's global `core.autocrlf`; each number includes the control round trip and the pending wait): the first `git.lineChanges` 332 ms (git detection, opening the repository, reading the blob), then 0.4–1.4 ms with the index text cached; after `git.stage` (158 ms) the next call reads the blob again and returns no ranges. Screenshots read in both themes: a modified bar, a deleted notch and an added bar where expected, no markers after staging, tabs in the modified and untracked colours, no markers for the untracked file. No keys were sent (owner at the PC).
- **Tests:** `cmd::git_lines` unit and property tests (line splitting, kinds, line endings, empty files, cache caps and generation, ranges in order and inside the buffer); `crates/engine/tests/git_lines.rs` (4 tests against real temp repositories: added/modified/deleted, a CRLF buffer against an autocrlf LF blob, staging drops the cache, an untracked file and no repository, bad params); Vitest `ui/tests/editor/gitGutter.test.ts` (12: reading, building, query on show, debounce, stale answers, failures, refresh, mapping), `ui/tests/vcs/vcsStatus.test.ts` (colours, reading, coalescing, events, tabs) and one tree test in `ui/tests/project/ProjectTree.test.ts`.
### Diff viewer (M4.3)
- **Where:** `ui/src/components/vcs/diff/`: `diff.ts` is the Pinia store of the diff tabs, `DiffView.vue` the view (loaded with `defineAsyncComponent`, so `@codemirror/merge` sits in its own 27 kB chunk, 9.7 kB gzip, not in the start bundle), `navigation.ts` the bridge to the next/previous change commands, `commands.ts` the handlers, supplied by the editor area. The project tree's context menu is `ui/src/components/project/TreeContextMenu.vue`.
- **Dependency:** `@codemirror/merge` 6.12 (MIT, Marijn Haverbeke; depends only on CodeMirror packages, `@lezer/highlight` and `style-mod`).
- **Commands** (UI commands, menu group Git): `vcs.showDiff {path?, staged?}` `Mod+Alt+Shift+D` opens the diff of a file (without a path: the active diff's or editor tab's file; enabled while a project is open); `vcs.nextChange` `Alt+Shift+]` and `vcs.previousChange` `Alt+Shift+[` move the cursor of the focused side (else the working copy) to the next or previous changed chunk, wrapping, and are enabled while a diff with changes shows. The shortcuts are Lutra's own: checked against the public default keymaps (Windows, macOS; the target uses other keys for show diff and next/previous difference), Lutra's registered shortcuts and CodeMirror's `basicSetup` keys.
- **Entry points:** double-click or Enter in the Changes window (`staged` true for a Staged row), the project tree's context menu (right click on a file, or Shift+F10 / the context-menu key on the selected file: Open, Show Diff), the palette and the menu.
- **Tabs:** diff tabs live in the diff store, not in the editor store: one per path and side (`staged:` / `work:` key), shown after the file tabs and titled "Diff: <name>" ("Diff: <name> (staged)" for the staged view). A diff covers the editor tab that was active when it was activated (the anchor; a synchronous watch on `editor.activeId` re-anchors while the diff opens its file and hides the diff when any other editor tab becomes active). Clicking a file tab hides it; closing the working copy's buffer, a project open or a project close closes diff tabs.
- **Left side:** `git.show {path, ref}` through `runWaiting`: `staged: true` compares with HEAD, otherwise with the index (equal to HEAD without staged changes, so a partly staged file shows only what is left to stage). A path missing at the ref is an empty side (a new file). Line breaks are normalised to `
` (git returns the blob as stored, LF under `core.autocrlf`; CodeMirror compares lines, so a CRLF working copy lines up). Re-read on `gitChanged`; a changed text replaces the left document in place. Binary or too large (`git.show`'s flags) shows a notice and opens nothing; a failed `git.show` shows git's message.
- **Right side:** the working copy is opened as an ordinary engine buffer through the editor store (it also gets its own file tab, hidden while the diff shows), so edits, saves, autosave, the journal and diagnostics work as in any tab. The right editor starts from the buffer's `BufferSync` state with the normal editor extensions; an update listener hands each local change to the sync (`sync.dispatch`, the diff of the documents if they ever differ), which sends `buffer.edit` as usual. Engine changes of the buffer (reload, an agent's edit) arrive as `bufferChanged`; once the sync has taken them over (`idle()`), the difference is applied to the right editor outside its undo history. A file missing from the working copy (deleted) shows an empty read-only side and a notice; the editor's error line is not raised for it.
- **Look:** both sides use the Lutra editor theme and the file's language; changed lines are tinted with `color-mix` of `--lt-vcs-deleted` (left) and `--lt-vcs-added` (right) into `--lt-editor-bg`, changed words more strongly, a change bar in each gutter, unchanged stretches over 8 lines collapse to a row (3 lines of context). No colour outside the tokens.
- **Tests:** `ui/tests/vcs/DiffView.test.ts` (21 Vitest tests against a fake engine: params and `git.show` parsing, EOL normalisation, index and HEAD sides, one tab per side, the palette without a path, bad params and no file as toasts, disabled without a project, edits on the right reaching `buffer.edit`, engine changes reaching the right side, the left side refresh on `gitChanged`, closing with the buffer, binary / too large / git error / deleted / new file, switching between diff and file tabs, next/previous change with wrap-around, the tree context menu by right click and by Shift+F10 with Escape).
## Decisions (M0)
| Question | Decision | Why |
@ -626,6 +639,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-26 | minor | M4.3: diff viewer (`vcs.showDiff`, `vcs.nextChange`, `vcs.previousChange`, `@codemirror/merge` loaded lazily, the project tree's context menu) |
| 2026-10-25 | minor | M4.4: `git.lineChanges` (index cache, `similar` line diff off the lock), gutter change markers, Git status colours in the tree and tabs |
| 2026-10-25 | minor | M4.2: Changes tool window (`vcs.openChanges`, `vcs.commit`, `vcs.refresh`, staging, commit after `flushDirty`) |
| 2026-10-25 | minor | M4.1: Git backend (`lutra-vcs`, `git.*` commands, `gitChanged`, `git.executable`) |