vscode: next-file / previous-file navigation across files in a Codev View Diff session

[amrmelsayed]

Problem

When reviewing a builder's diff via codev.viewDiff, the diff editor shows a unified diff for one file at a time with a file-list pane on the left. To move to the next file's diff, the reviewer has to take their hands off the editor and click in the file list (or focus the tree and arrow-key + Enter through it).

VSCode's built-in diff editor handles within-file change navigation natively — editor.action.diffReview.next / prev (F7 / Shift+F7) walk between hunks. But there is no equivalent for cross-file navigation in a multi-file diff session. Neither VSCode nor Codev wires a "next file in this diff session" command.

This is a real friction point for PR-review workflows. GitHub's PR review UI has j / k for exactly this. The Codev View Diff surface should have the equivalent.

Proposed mechanic

Two new commands scoped to the active Codev diff session:

• codev.diffNextFile — advance the diff editor to the next file in the file-list pane.
• codev.diffPreviousFile — go back to the previous file.

Both are keyboard-shortcut bindable, palette-discoverable, and operate on whatever file the diff editor is currently showing relative to its position in the ordered file list. They do not require the file-list pane to be focused — the focus stays on the diff editor.

Plan-gate decisions to lock

These are the design calls that affect the v1 shape; plan-approval picks each.

1. Default keybindings. Three reasonable conventions:

   • Cmd/Ctrl+Alt+Down / Cmd/Ctrl+Alt+Up (close to VSCode's "next/previous editor" semantics)
   • Alt+J / Alt+K (mirrors GitHub PR review's j / k)
   • Cmd/Ctrl+Shift+F7 / Cmd/Ctrl+Shift+Shift+F7 (extends VSCode's F7 in-file convention)
   • No default binding, palette-only (smallest blast radius; users add to keybindings.json themselves)
     Lean: palette-only by default + documentation, so we don't conflict with the user's existing custom bindings. Adopters who use the feature heavily bind it themselves.

2. Edge behavior at the start / end of the file list:

   • No-op silently (do nothing if already at first / last)
   • Wrap-around to the other end
   • Show a status-bar message ("First / last file in diff session")
     Lean: status-bar message + no wrap. Wrapping invites accidental loops; silent no-op feels broken.

3. Scope context resolution. Two scoping models:

   • Per-diff-session: track the currently-shown file for the active diff session and walk that session's file list.
   • Generic active diff editor: any diff editor (including non-Codev ones the user happens to open). Reads the file list from whatever provider is active.
     Lean: per-diff-session for v1 (Codev's View Diff only). Generic mode is a future enhancement once the basic flow proves the UX shape.

4. Behavior when the file list isn't visible. If the user has collapsed the left pane, do the commands still work? Lean: yes, file list visibility is a display preference and shouldn't gate the keyboard navigation.

5. Saving state across sessions. If the reviewer pauses (closes the diff editor) and re-opens for the same builder, should the diff editor restore to the file they were last viewing? Out of scope for this issue; cleanest to just open at the first file each time, and let the user navigate from there.

Acceptance criteria

• codev.diffNextFile and codev.diffPreviousFile are registered as palette-discoverable commands.
• Invoking next when not at the last file advances the diff editor to the next file; invoking previous walks back.
• Edge behavior per plan-gate decision Context Window Optimization - AI Needs Project Knowledge Without Breaking Limits #2 (status-bar message + no wrap by default).
• Focus stays on the diff editor (the file-list pane does not steal focus).
• The file ordering matches what the file-list pane displays (so visual order = navigation order).
• Commands work when the file-list pane is collapsed or hidden.
• No regression to existing codev.viewDiff flow or the within-file F7 / Shift+F7 navigation (those continue to work, walking hunks within the currently-selected file).
• Unit tests for: ordering matches file-list order, next-at-end / prev-at-start no-op with status message, multi-builder isolation (each builder's diff session has its own file list and pointer).
• Manual verification at dev-approval: spawn two builders with non-trivial diffs, open both diff sessions, walk through files via the new commands, verify isolation and ordering.

Why PIR, not AIR

UI / UX shape benefits from plan-gate design review (the five plan-gate decisions above are real choices, not implementation details). And the behavior is the kind that's "looks right in unit test, awkward in practice" until you actually walk it on a real builder's diff — dev-approval gate is load-bearing for that visual / kinesthetic verification.

Implementation is small (~50-100 LOC + tests) but design discipline matters here.

Out of scope

• Generic-mode (any-diff-editor) navigation. v1 is Codev-diff-session-only; generic is a follow-up if there's demand.
• Restoring last-viewed file on re-opening the diff session.
• Cross-builder navigation ("next builder's diff after I'm done with this one's last file"). Different UX entirely; if useful, file separately.
• Rebinding the existing within-file F7 / Shift+F7 — those stay as-is.
• A visual breadcrumb / current-file indicator in the diff editor title. Useful but additive; the file-list pane already shows which file is active.

Related

• PR vscode: Forward file/symbol/hunk/selection references into the builder PTY (#789) #1023 / vscode: inject file/hunk reference into builder PTY from the unified-diff editor (codelens) #789 — codelens in the unified diff editor (closest neighborhood; same codev.viewDiff surface).
• PR [Bugfix #804] vscode: don't force-create a second editor group for builder terminals #1041 / vscode: don't force-create a second editor group when spawning builder terminals — attach if exists, else use the default group #804 — terminal-group resolution work in the same VSCode extension; not directly related but a nearby example of how Codev wires VSCode-side ergonomics.
• VSCode native: editor.action.diffReview.next / editor.action.diffReview.prev — the within-file equivalents that this issue extends across files.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).