git-reviewer 2.12.0 → 2.13.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-335-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-355-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 When an agent writes the code, reading it becomes the bottleneck — and the tool
@@ -141,7 +141,7 @@ is nothing to configure:
 | Working directory clean | The last commit against its parent |
 | No commits yet | Every tracked and untracked file, as wholly new |
 
-### Comparing branches
+### Comparing branches and commits
 
 Those defaults cover the common case with nothing to set up, but a branch you
 have worked on for a day is several commits deep, and the default scope only
@@ -178,6 +178,29 @@ commits that add a file and then delete it produce no diff between the ends —
 correctly — and that reads as *"2 commits undo each other"*, not as *"nothing
 to review"*.
 
+#### Reviewing commit by commit
+
+Whenever the review is made of commits, the sidebar lists them above the files:
+the commits a comparison is made of, oldest first, or the branch's recent
+history when you are looking at its last commit.
+
+- **Click** a commit to review it on its own, with its full message above the
+  diff — often the only place the author says *why*.
+- **Shift-click** a second to review the run between them, both ends included.
+  From the last commit, shift-clicking three rows down is "the last three
+  commits"; inside a comparison, it skips the ones you have already read.
+- **`[`** and **`]`** step one commit older or newer, and **All commits** goes
+  back to the whole comparison.
+
+That is the same gesture a pull request's commit picker uses, for the same
+reasons: a large change reads better in the order it was written, and one
+commit of renames is easier to skip than to read around.
+
+A run has to be one unbroken line of history. To diff two points that are not
+— a commit on one branch against another branch — use **Compare**; its pickers
+list recent commits of whichever branch you are comparing, right after the
+local branches.
+
 Comments are kept when you switch between comparisons. One on a file that is
 not in the current view stays in the comments list, marked **Not in this
 view**, and is back in place whenever you open a view that includes the file.
@@ -305,8 +328,9 @@ The UI is a client of this; nothing is hidden from you.
 | Endpoint | Purpose |
 |---|---|
 | `GET /api/health` | Liveness, plus the number of open sessions |
-| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files. Pass `base` (and optionally `head`) to compare two refs from their merge base |
-| `GET /api/refs/:repoId` | Branches, remote branches, tags and recent commits, for choosing what to compare |
+| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files. Pass `base` (and optionally `head`) to compare two refs from their merge base, or `commits: { from, to }` to review one commit or an unbroken run of them, both ends included |
+| `GET /api/refs/:repoId` | Branches, remote branches, tags and recent commits, for choosing what to compare. `?head=` makes the commits those of another branch |
+| `GET /api/log/:repoId` | Commits with their messages: `?base=&head=` for a comparison's commits, oldest first, or `?head=` alone for recent history, newest first |
 | `GET /api/commits/:repoId` | Recent commits only; kept for callers of 2.11 |
 | `GET /api/alive` | Held open by the page; when the last one closes, a terminal run stops |
 | `GET /api/file/:repoId/:path` | The file's diff, as structured lines |
@@ -338,7 +362,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 335 tests
+npm test              # 355 tests
 npm run test:watch
 npm run test:coverage
 ```

package/lib/agent.js

@@ -205,6 +205,17 @@ function describeScope({ repository, mode, range }) {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  if (mode === 'range' && range?.kind === 'commits') {
+    // Commits themselves, picked from a list. Both ends are *in* the review,
+    // which is the difference from a comparison and worth saying: an agent
+    // told "between A and B" would reasonably assume A's own changes were
+    // outside it.
+    if (range.first === range.last) {
+      return `Reviewed: commit ${range.last}${range.subject ? ` ("${range.subject}")` : ''} on its own, against its parent.`;
+    }
+    return `Reviewed: ${range.commits} commits, ${range.first} through ${range.last} inclusive, as a single combined diff.`;
+  }
+
   if (mode === 'range' && range) {
     // Both ends, and the count, because the count is the only thing that
     // distinguishes "one commit of work" from "nine" once the diff has been

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Review your coding agent's changes like a pull request — locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",

package/public/app.js

@@ -166,9 +166,10 @@ const PICKERS = {
  * works; a repository whose refs will not list is not a reason to refuse to
  * compare it.
  */
-async function loadRefs(repoId) {
+async function loadRefs(repoId, head) {
   try {
-    const response = await fetch(`${API_BASE}/refs/${repoId}`);
+    const query = head ? `?${new URLSearchParams({ head })}` : '';
+    const response = await fetch(`${API_BASE}/refs/${repoId}${query}`);
     currentRefs = response.ok ? await response.json() : null;
   } catch {
     currentRefs = null;
@@ -207,12 +208,15 @@ function fillPicker(end) {
       `${branch.name}${branch.name === refs.current ? ' (current)' : ''}  ·  ${branch.when}`,
       branch.name
     )));
-    group('Remote branches', refs.remotes.map(branch => new Option(`${branch.name}  ·  ${branch.when}`, branch.name)));
-    group('Tags', refs.tags.map(tag => new Option(`${tag.name}  ·  ${tag.when}`, tag.name)));
+    // Commits second, not last. In 2.12 they came after every remote branch
+    // and tag -- option 51 of 81 in this project's own repository -- which is
+    // why comparing a commit felt like a feature that had been removed.
     group(
-      refs.current ? `Recent commits on ${refs.current}` : 'Recent commits',
+      'Recent commits',
       refs.commits.map(commit => new Option(`${commit.short}  ·  ${commit.subject}  ·  ${commit.when}`, commit.sha))
     );
+    group('Remote branches', refs.remotes.map(branch => new Option(`${branch.name}  ·  ${branch.when}`, branch.name)));
+    group('Tags', refs.tags.map(tag => new Option(`${tag.name}  ·  ${tag.when}`, tag.name)));
   }
 
   select.appendChild(new Option('Other: a tag, HEAD~5, a sha…', OTHER_REF));
@@ -353,15 +357,89 @@ function renderScope(data) {
     el.textContent = text;
     return el;
   };
-  const setNote = text => {
+  const setNote = (text, { message = false } = {}) => {
     note.textContent = text ?? '';
     note.classList.toggle('hidden', !text);
+    // A commit message keeps its line breaks; an explanation reflows.
+    note.classList.toggle('scope-note-message', Boolean(text) && message);
   };
 
+  const nav = document.getElementById('commitNav');
+  const position = document.getElementById('commitPosition');
+  const allCommits = document.getElementById('allCommitsBtn');
+  nav.classList.add('hidden');
+  allCommits.classList.add('hidden');
+  reset.textContent = 'Stop comparing';
+
   bar.classList.remove('hidden');
   label.replaceChildren();
   const branch = currentRefs?.current;
 
+  if (data.mode === 'range' && data.range?.kind === 'commits') {
+    // One commit, or a run of them, picked from the commits list.
+    const run = data.range;
+    const single = run.first === run.last;
+    const chrono = chronologicalCommits(commitContext);
+    const index = chrono.findIndex(commit => commit.sha === run.first);
+    const commit = single && index !== -1 ? chrono[index] : null;
+    const files = plural(data.files.length, 'file') + ' changed';
+
+    if (single) {
+      label.append('Commit ', strong(run.headName));
+    } else {
+      label.append(strong(run.baseName), ' \u2026 ', strong(run.headName));
+    }
+
+    const inComparison = commitContext?.kind === 'comparison';
+    if (inComparison) {
+      const outer = commitContext.range;
+      label.append(' in ', strong(displayRef(outer.baseName ?? outer.base)), ' \u2192 ',
+        strong(displayRef(outer.headName ?? outer.head)));
+    } else if (branch) {
+      label.append(' on ', strong(branch));
+    }
+
+    meta.textContent = single
+      ? `${commit?.subject ?? run.subject ?? ''} \u00b7 ${files}`
+      : `${plural(run.commits, 'commit')} \u00b7 ${files}`;
+
+    // The message is review material -- often the only place the author says
+    // why -- so a single commit shows its body, not just its subject line.
+    if (single && commit?.body) {
+      setNote(commit.body, { message: true });
+    } else if (!single) {
+      setNote(`Reviewing ${plural(run.commits, 'commit')} as one combined diff, from ${run.baseName} through ${run.headName}.`);
+    } else {
+      setNote(null);
+    }
+
+    if (single && index !== -1) {
+      nav.classList.remove('hidden');
+      // "2 of 3" means something inside a comparison; inside a branch's
+      // history it would count from wherever the list happened to stop.
+      position.textContent = inComparison ? `${index + 1} of ${chrono.length}` : '';
+      document.getElementById('prevCommitBtn').disabled = index === 0;
+      document.getElementById('nextCommitBtn').disabled = index === chrono.length - 1;
+    }
+
+    if (inComparison) {
+      row.classList.remove('hidden');
+      const outer = commitContext.range;
+      selectRef('base', outer.baseName, outer.base);
+      selectRef('head', outer.headName, outer.head);
+      allCommits.textContent = `All ${plural(chrono.length, 'commit')}`;
+      allCommits.classList.remove('hidden');
+      toggle.classList.add('hidden');
+      reset.classList.remove('hidden');
+    } else {
+      row.classList.add('hidden');
+      toggle.classList.remove('hidden');
+      reset.textContent = 'Back to latest';
+      reset.classList.remove('hidden');
+    }
+    return;
+  }
+
   if (data.mode === 'range' && data.range) {
     const range = data.range;
     const base = displayRef(range.baseName ?? range.base);
@@ -401,20 +479,265 @@ function renderScope(data) {
   if (data.mode === 'lastCommit') {
     label.append('Last commit');
     if (branch) label.append(' on ', strong(branch));
-    const tip = currentRefs?.commits?.[0];
+    const tip = commitContext?.commits?.[0] ?? currentRefs?.commits?.[0];
     meta.textContent = tip ? `${tip.subject} · ${tip.short}` : '';
+    setNote(tip?.body || null, { message: true });
+
+    // One click back through history from here -- the first thing someone
+    // looking at the last commit is likely to want next.
+    if ((commitContext?.commits?.length ?? 0) > 1) {
+      nav.classList.remove('hidden');
+      position.textContent = '';
+      document.getElementById('prevCommitBtn').disabled = false;
+      document.getElementById('nextCommitBtn').disabled = true;
+    }
   } else {
     label.append('Uncommitted changes');
     if (branch) label.append(' on ', strong(branch));
     meta.textContent = plural(data.files.length, 'file') + ' changed';
+    setNote(null);
   }
 
-  setNote(null);
   row.classList.add('hidden');
   toggle.classList.remove('hidden');
   reset.classList.add('hidden');
 }
 
+// --- commits: reviewing them one at a time, or a run of them -----------------
+
+// What the commits list is showing. `comparison` is the commits a Compare is
+// made of, oldest first; `history` is the recent history of the branch when
+// the view is its last commit, newest first. Null for the working tree, which
+// has no commits to list. `range` keeps the outer comparison, so narrowing to
+// one commit does not lose what it was a commit *of*.
+let commitContext = null;
+
+// Which of those commits the review currently shows, as `{from, to}` shas,
+// oldest first; null for all of them.
+let commitSelection = null;
+
+// The commit a shift-click extends from.
+let commitAnchor = null;
+
+/** The context's commits, oldest first, whichever order the list shows them in. */
+function chronologicalCommits(context) {
+  if (!context) return [];
+  return context.order === 'newest-first' ? [...context.commits].reverse() : context.commits;
+}
+
+/**
+ * The run between two commits of a list, oldest first -- whichever was
+ * clicked first. A shift-click upwards and one downwards select the same run.
+ *
+ * @param {{sha: string}[]} chronological commits, oldest first
+ * @returns {[string, string]|null} [from, to]
+ */
+function orderedRun(chronological, a, b) {
+  const i = chronological.findIndex(commit => commit.sha === a);
+  const j = chronological.findIndex(commit => commit.sha === b);
+  if (i === -1 || j === -1) return null;
+  return i <= j
+    ? [chronological[i].sha, chronological[j].sha]
+    : [chronological[j].sha, chronological[i].sha];
+}
+
+/**
+ * Where a step lands, or -1 if there is nowhere to go.
+ *
+ * From "all commits" a step forward starts at the oldest -- the beginning of
+ * the story -- and a step back starts at the newest. Stepping never wraps:
+ * reaching the end of a branch and silently landing on its first commit
+ * again reads as the list having started over.
+ *
+ * @param {number} length
+ * @param {number} current index of the one commit shown, or -1 if not one
+ * @param {1|-1} direction +1 newer, -1 older
+ */
+function stepIndex(length, current, direction) {
+  if (length === 0) return -1;
+  if (current === -1) return direction > 0 ? 0 : length - 1;
+  const next = current + direction;
+  return next >= 0 && next < length ? next : -1;
+}
+
+/**
+ * "3 hours ago" as "3h", for a list where the subject needs the width.
+ *
+ * Git's relative dates are written for a sentence, and in a 320px sidebar
+ * "2 seconds ago" took more room than the commit subject beside it. The full
+ * phrase stays in the row's tooltip. Anything not recognised is returned as
+ * it came, rather than guessed at.
+ *
+ * @param {string} when git's %cr, e.g. "3 weeks ago" or "1 year, 2 months ago"
+ */
+function compactWhen(when) {
+  const match = /^(\d+) (second|minute|hour|day|week|month|year)s?(?:, .*)? ago$/.exec(when ?? '');
+  if (!match) return when ?? '';
+  const unit = { second: 's', minute: 'm', hour: 'h', day: 'd', week: 'w', month: 'mo', year: 'y' }[match[2]];
+  return `${match[1]}${unit}`;
+}
+
+/** Fetch a commits list for the context the review is in. */
+async function fetchCommitContext(repoId, kind, { base, head, range }) {
+  const query = new URLSearchParams({ head });
+  if (base) query.set('base', base);
+
+  try {
+    const response = await fetch(`${API_BASE}/log/${repoId}?${query}`);
+    if (!response.ok) return null;
+    const log = await response.json();
+    return { kind, base, head, range, ...log };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide what the commits list shows after a load.
+ *
+ * A load that narrows to commits keeps the list it narrowed from; anything
+ * else rebuilds it. The branch history offered with "last commit" is the same
+ * gesture as a comparison's commits: this is where "review the changes since
+ * that commit", which 2.11 had as a dropdown and 2.12 buried under forty
+ * branches, lives now.
+ */
+async function refreshCommitContext(data, scope) {
+  if (scope.commits && commitContext) {
+    commitSelection = { from: data.range.first, to: data.range.last };
+    return;
+  }
+
+  commitAnchor = null;
+  commitSelection = null;
+
+  if (data.mode === 'range' && data.range) {
+    commitContext = await fetchCommitContext(data.repoId, 'comparison', {
+      base: data.range.base, head: data.range.head, range: data.range
+    });
+  } else if (data.mode === 'lastCommit' && data.range) {
+    commitContext = await fetchCommitContext(data.repoId, 'history', { head: data.range.head });
+    // The last commit is itself one of the listed commits, so it is shown as
+    // the selected one, and shift-clicking further down selects "since then".
+    commitSelection = { from: data.range.head, to: data.range.head };
+    commitAnchor = data.range.head;
+  } else {
+    commitContext = null;
+  }
+}
+
+/** Draw the commits list, marking the ones the review is of. */
+function renderCommitList() {
+  const section = document.getElementById('commitsSection');
+  const list = document.getElementById('commitsList');
+  const title = document.getElementById('commitsTitle');
+  const count = document.getElementById('commitCount');
+  const truncated = document.getElementById('commitsTruncated');
+
+  if (!commitContext || commitContext.commits.length === 0) {
+    section.classList.add('hidden');
+    return;
+  }
+
+  section.classList.remove('hidden');
+  title.textContent = commitContext.kind === 'comparison'
+    ? 'Commits in this comparison'
+    : `Recent commits${currentRefs?.current ? ` on ${currentRefs.current}` : ''}`;
+  count.textContent = String(commitContext.total);
+  truncated.classList.toggle('hidden', !commitContext.truncated);
+  truncated.textContent = commitContext.truncated
+    ? `Showing ${commitContext.commits.length} of ${commitContext.total}. Anything further back is still reachable by typing it into Compare.`
+    : '';
+
+  // Which rows are in the review: everything from `from` to `to` in time,
+  // or every row when there is no selection.
+  const chrono = chronologicalCommits(commitContext);
+  const inRun = new Set();
+  if (commitSelection) {
+    const i = chrono.findIndex(c => c.sha === commitSelection.from);
+    const j = chrono.findIndex(c => c.sha === commitSelection.to);
+    if (i !== -1 && j !== -1) chrono.slice(Math.min(i, j), Math.max(i, j) + 1).forEach(c => inRun.add(c.sha));
+  } else {
+    chrono.forEach(c => inRun.add(c.sha));
+  }
+
+  // Built from nodes: subjects and author names are whatever the repository
+  // says, and they are shown, never parsed as markup.
+  const rows = commitContext.commits.map(commit => {
+    const item = document.createElement('li');
+    item.className = 'commit-item';
+    item.dataset.sha = commit.sha;
+    item.tabIndex = 0;
+    item.setAttribute('role', 'option');
+    const selected = inRun.has(commit.sha) && commitSelection !== null;
+    item.setAttribute('aria-selected', String(selected));
+    if (selected) item.classList.add('commit-item-selected');
+    item.title = `${commit.subject}\n${commit.short} · ${commit.author} · ${commit.when}${commit.merge ? ' · merge' : ''}`;
+
+    const sha = document.createElement('span');
+    sha.className = 'commit-sha';
+    sha.textContent = commit.short;
+    const subject = document.createElement('span');
+    subject.className = 'commit-subject';
+    subject.textContent = commit.subject;
+    const when = document.createElement('span');
+    when.className = 'commit-when';
+    when.textContent = compactWhen(commit.when);
+
+    item.append(sha, subject);
+    if (commit.merge) {
+      const merge = document.createElement('span');
+      merge.className = 'commit-merge';
+      merge.textContent = 'merge';
+      item.append(merge);
+    }
+    item.append(when);
+    return item;
+  });
+  list.replaceChildren(...rows);
+
+  const current = list.querySelector('.commit-item-selected');
+  if (current) current.scrollIntoView({ block: 'nearest' });
+}
+
+/**
+ * Review one commit, or -- with shift -- the run from the anchor to it.
+ *
+ * @param {string} sha
+ * @param {boolean} extend
+ */
+function selectCommit(sha, extend) {
+  if (!commitContext) return;
+
+  if (extend && commitAnchor) {
+    const run = orderedRun(chronologicalCommits(commitContext), commitAnchor, sha);
+    if (run) loadRepo({ commits: { from: run[0], to: run[1] } });
+    return;
+  }
+
+  commitAnchor = sha;
+  loadRepo({ commits: { from: sha, to: sha } });
+}
+
+/** Step one commit older (-1) or newer (+1): commit-by-commit review. */
+function stepCommit(direction) {
+  if (!commitContext) return;
+  const chrono = chronologicalCommits(commitContext);
+  const single = commitSelection && commitSelection.from === commitSelection.to
+    ? chrono.findIndex(c => c.sha === commitSelection.from)
+    : -1;
+  const next = stepIndex(chrono.length, single, direction);
+  if (next !== -1) selectCommit(chrono[next].sha, false);
+}
+
+/** Back from one commit to the whole comparison it was part of. */
+function showAllCommits() {
+  if (commitContext?.kind !== 'comparison') return;
+  // By the names that were picked, so the bar still says main -> feature/auth
+  // rather than two SHAs.
+  const { range } = commitContext;
+  loadRepo({ base: range.baseName ?? range.base, head: range.headName ?? range.head });
+}
+
 /** Empty the diff pane, so a finished comparison cannot leave the last one's file on screen. */
 function clearCodePane() {
   currentFile = null;
@@ -435,9 +758,10 @@ function showEmptyFileList(message) {
 /**
  * Load a repository, optionally as a range between two commits.
  *
- * @param {{base?: string, head?: string}} [scope] omit for the default:
- *   uncommitted changes, falling back to the last commit on a clean tree.
- *   `head` defaults to HEAD on the server.
+ * @param {{base?: string, head?: string, commits?: {from: string, to: string}}} [scope]
+ *   omit for the default: uncommitted changes, falling back to the last
+ *   commit on a clean tree. `base`/`head` compare two refs from their merge
+ *   base; `commits` reviews one commit or an unbroken run of them, inclusive.
  */
 async function loadRepo(scope = {}) {
   const repoPath = document.getElementById('repoPath').value.trim();
@@ -454,9 +778,11 @@ async function loadRepo(scope = {}) {
     const response = await fetch(`${API_BASE}/load-repo`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(scope.base
-        ? { repoPath, base: scope.base, ...(scope.head ? { head: scope.head } : {}) }
-        : { repoPath })
+      body: JSON.stringify(
+        scope.commits ? { repoPath, commits: scope.commits }
+          : scope.base ? { repoPath, base: scope.base, ...(scope.head ? { head: scope.head } : {}) }
+            : { repoPath }
+      )
     });
 
     const data = await response.json();
@@ -476,10 +802,14 @@ async function loadRepo(scope = {}) {
       setRepoButton(data.repoPath);
     }
 
-    // Before renderScope, which needs the options present to select the
-    // current ends among them, and the current branch to name it.
-    await loadRefs(data.repoId);
+    // In this order: the commits list first, because it decides which head
+    // the pickers' commits should follow; the refs next, because renderScope
+    // needs the options present to select the current ends among them and
+    // the current branch to name it; then the bar and the list.
+    await refreshCommitContext(data, scope);
+    await loadRefs(data.repoId, commitContext?.head ?? data.range?.head);
     renderScope(data);
+    renderCommitList();
 
     if (data.files.length === 0) {
       // A range with no files is a real answer, not a failure: every change
@@ -493,7 +823,11 @@ async function loadRepo(scope = {}) {
         clearStatus();
         hidePicker();
         displayFiles([]);
-        showEmptyFileList('No files differ between these two.');
+        showEmptyFileList(data.range?.kind !== 'commits'
+          ? 'No files differ between these two.'
+          : data.range.first === data.range.last
+            ? 'This commit changes no files.'
+            : 'These commits change no files between them.');
         updateCommentsSidebar();
         // Or the previous comparison's file stays on screen under a bar that
         // says there are no files, and reads as part of this one.
@@ -2082,7 +2416,11 @@ function getKeyboardShortcut(key, targetTagName, modifiers = {}) {
   // must be checked before the typing guard.
   if (key === 'Escape') return 'escape';
 
-  if (targetTagName === 'INPUT' || targetTagName === 'TEXTAREA') {
+  // SELECT as well as the text fields. With focus in one of the compare
+  // pickers, a letter is the browser's type-ahead -- "c" jumps to the first
+  // option starting with c -- and it also opened a comment box, because only
+  // INPUT and TEXTAREA were excluded here when the pickers arrived in 2.12.
+  if (targetTagName === 'INPUT' || targetTagName === 'TEXTAREA' || targetTagName === 'SELECT') {
     return null;
   }
 
@@ -2094,6 +2432,8 @@ function getKeyboardShortcut(key, targetTagName, modifiers = {}) {
     'n': 'nextComment',
     'p': 'prevComment',
     'c': 'commentFocus',
+    '[': 'prevCommit',
+    ']': 'nextCommit',
     '?': 'help'
   };
 
@@ -2132,6 +2472,25 @@ document.addEventListener('DOMContentLoaded', () => {
     }
   });
 
+  // The commits list: click reviews one, shift-click the run to it. Enter
+  // and shift+Enter do the same from the keyboard, since every row is
+  // focusable.
+  const commitsList = document.getElementById('commitsList');
+  commitsList.addEventListener('click', (e) => {
+    const item = e.target.closest('.commit-item');
+    if (!item) return;
+    // Shift-click also extends the browser's text selection across the rows
+    // it passes; that is noise here, not a gesture anyone meant.
+    if (e.shiftKey) window.getSelection()?.removeAllRanges();
+    selectCommit(item.dataset.sha, e.shiftKey);
+  });
+  commitsList.addEventListener('keydown', (e) => {
+    const item = e.target.closest('.commit-item');
+    if (!item || e.key !== 'Enter') return;
+    e.preventDefault();
+    selectCommit(item.dataset.sha, e.shiftKey);
+  });
+
   for (const end of ['base', 'head']) {
     document.getElementById(PICKERS[end].other).addEventListener('keypress', (e) => {
       if (e.key === 'Enter') {
@@ -2163,6 +2522,12 @@ document.addEventListener('DOMContentLoaded', () => {
     } else if (action === 'commentFocus') {
       e.preventDefault();
       handleCommentShortcut();
+    } else if (action === 'prevCommit') {
+      e.preventDefault();
+      stepCommit(-1);
+    } else if (action === 'nextCommit') {
+      e.preventDefault();
+      stepCommit(1);
     } else if (action === 'help') {
       e.preventDefault();
       document.getElementById('helpButton').click();

package/public/index.html

@@ -62,7 +62,16 @@
           <span id="scopeMeta" class="scope-meta"></span>
         </div>
         <div class="scope-actions">
-          <button id="compareToggle" class="scope-action" onclick="openCompare()">Compare branches</button>
+          <div id="commitNav" class="commit-nav hidden" role="group" aria-label="Step through commits">
+            <button id="prevCommitBtn" class="scope-action" onclick="stepCommit(-1)"
+              title="Older commit ( [ )" aria-label="Older commit">&#8249;</button>
+            <span id="commitPosition" class="commit-position"></span>
+            <button id="nextCommitBtn" class="scope-action" onclick="stepCommit(1)"
+              title="Newer commit ( ] )" aria-label="Newer commit">&#8250;</button>
+          </div>
+          <button id="allCommitsBtn" class="scope-action hidden" onclick="showAllCommits()">All commits</button>
+          <button id="compareToggle" class="scope-action" onclick="openCompare()"
+            title="Compare two branches, tags or commits">Compare</button>
           <button id="scopeResetBtn" class="scope-action hidden" onclick="resetScope()">Stop comparing</button>
         </div>
       </div>
@@ -186,7 +195,7 @@
           <span class="help-keys">
             <kbd>⌘</kbd><kbd>Enter</kbd> save · <kbd>Esc</kbd> cancel ·
             <kbd>↑</kbd><kbd>↓</kbd><kbd>j</kbd><kbd>k</kbd> files ·
-            <kbd>n</kbd><kbd>p</kbd> comments · <kbd>c</kbd> new comment · <kbd>?</kbd> help
+            <kbd>n</kbd><kbd>p</kbd> comments · <kbd>[</kbd><kbd>]</kbd> commits · <kbd>c</kbd> new comment · <kbd>?</kbd> help
           </span>
           <button class="help-done" onclick="closeHelp()">Got it</button>
         </div>
@@ -194,6 +203,20 @@
     </div>
 
     <aside id="sidebar" class="sidebar hidden">
+      <!-- The commits a review is made of, when it is made of commits. Click
+           one to review it on its own; shift-click a second to review the run
+           between them -- the same gesture a pull request's commit picker
+           uses, so it does not have to be learned twice. -->
+      <section id="commitsSection" class="commits-section hidden" aria-labelledby="commitsTitle">
+        <div class="sidebar-header">
+          <h2 id="commitsTitle">Commits</h2>
+          <span id="commitCount" class="file-count"></span>
+        </div>
+        <p class="commits-hint">Click one · <kbd>Shift</kbd>-click a run · <kbd>[</kbd><kbd>]</kbd> step</p>
+        <ol id="commitsList" class="commits-list" role="listbox" aria-label="Commits" aria-multiselectable="true"></ol>
+        <p id="commitsTruncated" class="commits-truncated hidden"></p>
+      </section>
+
       <div class="sidebar-header">
         <h2>Changed Files</h2>
         <span id="fileCount" class="file-count"></span>

package/public/style.css

@@ -2072,3 +2072,147 @@ button:disabled {
   letter-spacing: 0.04em;
   color: #6a737d;
 }
+
+/* ---------------------------------------------------------------------------
+ * Commits: the ones a review is made of, above the files they touch.
+ * ------------------------------------------------------------------------ */
+
+.commits-section {
+  border-bottom: 1px solid #e1e4e8;
+}
+
+.commits-hint {
+  margin: 0;
+  padding: 0 20px 8px;
+  font-size: 11px;
+  color: #6a737d;
+}
+
+.commits-hint kbd {
+  font-size: 10px;
+  padding: 0 4px;
+  border: 1px solid #d1d5da;
+  border-bottom-width: 2px;
+  border-radius: 3px;
+  background: #fafbfc;
+}
+
+/* A bounded height, so a branch of forty commits does not push the files it
+ * touches off the bottom of the sidebar. */
+.commits-list {
+  list-style: none;
+  margin: 0;
+  padding: 0 8px 8px;
+  max-height: 34vh;
+  overflow-y: auto;
+}
+
+.commit-item {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 6px 10px;
+  margin: 2px 0;
+  border-radius: 6px;
+  border-left: 3px solid transparent;
+  font-size: 12px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.commit-item:hover {
+  background: #f3f4f6;
+}
+
+.commit-item:focus-visible {
+  outline: 2px solid #0366d6;
+  outline-offset: -2px;
+}
+
+.commit-item-selected {
+  background: #f1f8ff;
+  border-left-color: #0366d6;
+}
+
+.commit-sha {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  color: #0366d6;
+  flex-shrink: 0;
+}
+
+.commit-subject {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: #24292e;
+}
+
+.commit-when {
+  flex-shrink: 0;
+  font-size: 11px;
+  color: #6a737d;
+}
+
+.commit-merge {
+  flex-shrink: 0;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  color: #6f42c1;
+}
+
+.commits-truncated {
+  margin: 0;
+  padding: 0 20px 8px;
+  font-size: 11px;
+  color: #6a737d;
+}
+
+/* Stepping one commit at a time, from the scope bar. */
+.commit-nav {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.commit-nav .scope-action {
+  padding: 5px 10px;
+  font-size: 15px;
+  line-height: 1;
+}
+
+.commit-nav .scope-action:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.commit-nav .scope-action:disabled:hover {
+  background: #fff;
+  border-color: #d1d5da;
+}
+
+.commit-position {
+  min-width: 0;
+  font-size: 12px;
+  color: #586069;
+  white-space: nowrap;
+}
+
+.commit-position:empty {
+  display: none;
+}
+
+/* A commit message keeps its own line breaks; it is prose someone wrote in
+ * paragraphs, and reflowing it into one line loses its lists. */
+.scope-note-message {
+  white-space: pre-line;
+  font-size: 13px;
+  color: #24292e;
+  padding-left: 10px;
+  border-left: 3px solid #d1d5da;
+  max-height: 8.5em;
+  overflow-y: auto;
+}

package/server.js

@@ -73,6 +73,11 @@ const COMMIT_LIST_LIMIT = 30;
 // cut are the least recently touched and are still reachable by typing.
 const REF_LIST_LIMIT = 40;
 
+// How many commits the commits list shows. A branch of more than this is a
+// review nobody is doing commit by commit; the list says it is truncated
+// rather than pretending the rest are not there.
+const LOG_LIMIT = 200;
+
 function createApp(options = {}) {
   const {
     reviewsDir = resolveReviewsDir(),
@@ -321,6 +326,90 @@ function createApp(options = {}) {
     };
   }
 
+  /**
+   * The range for reviewing commits themselves: one, or an unbroken run.
+   *
+   * Different from comparing two refs. `from` and `to` are both *in* the
+   * review -- clicking one commit means that commit's changes, and
+   * shift-clicking a second means everything from the first through the
+   * second -- so the diff starts at the parent of `from`, not at `from`.
+   * That is what GitHub does when you pick commits inside a pull request, and
+   * what "review commit 3 of 5" has to mean.
+   *
+   * `from` has to come before `to` on one line of history. Two commits on
+   * different branches have no run between them; that is a comparison, and
+   * the compare pickers exist for it.
+   *
+   * @throws {Error} with a message meant for the page
+   */
+  async function resolveCommitRun(git, fromRef, toRef) {
+    for (const [label, ref] of [['first commit', fromRef], ['last commit', toRef]]) {
+      if (!looksLikeRef(ref)) throw new Error(`That ${label} does not look like a commit.`);
+    }
+
+    const resolve = async ref => {
+      try {
+        return (await git.revparse([`${ref}^{commit}`])).trim();
+      } catch {
+        throw new Error(`No commit called "${ref}" in this repository.`);
+      }
+    };
+    const first = await resolve(fromRef);
+    const last = await resolve(toRef);
+
+    // Ancestry through output, not exit code: `merge-base --is-ancestor`
+    // answers only by exiting 1, and simple-git resolves a silent non-zero
+    // exit -- so it reported every pair as ordered, including main before a
+    // branch that main was not an ancestor of. The merge base of an ancestor
+    // and its descendant is the ancestor, and that is checkable.
+    const mergeBase = (await git.raw(['merge-base', first, last]).catch(() => '')).trim();
+    if (mergeBase !== first) {
+      throw new Error(
+        `${first.slice(0, 7)} does not come before ${last.slice(0, 7)} on one line of history, ` +
+        'so there is no run of commits between them. Use Compare to diff two unrelated points.'
+      );
+    }
+
+    // A root commit has no parent. Its "before" is the empty tree, which is
+    // also how `git show` presents a root commit: every file added.
+    let from;
+    let hasParent = true;
+    try {
+      from = (await git.revparse([`${first}^`])).trim();
+    } catch {
+      hasParent = false;
+      from = (await git.raw(['hash-object', '-t', 'tree', '/dev/null'])).trim();
+    }
+
+    const count = Number((await git.raw(['rev-list', '--count', hasParent ? `${from}..${last}` : last, '--'])).trim());
+    const subject = first === last
+      ? (await git.raw(['log', '-1', '--format=%s', last, '--']).catch(() => '')).trim()
+      : null;
+
+    return {
+      kind: 'commits',
+      first,
+      last,
+      base: from,
+      head: last,
+      from,
+      commits: Number.isFinite(count) ? count : 1,
+      behind: 0,
+      baseName: first.slice(0, 7),
+      headName: last.slice(0, 7),
+      ...(subject ? { subject } : {})
+    };
+  }
+
+  /** What to say about a commit or a run of them once loaded. */
+  function describeCommitRun(range, fileCount) {
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+    const files = fileCount === 0 ? 'no files changed' : plural(fileCount, 'changed file');
+    return range.first === range.last
+      ? `Commit ${range.headName}${range.subject ? `: ${range.subject}` : ''} — ${files}`
+      : `${plural(range.commits, 'commit')}, ${range.baseName} through ${range.headName} — ${files}`;
+  }
+
   /**
    * The changed files of a range, with the status git gives each one.
    *
@@ -382,9 +471,9 @@ function createApp(options = {}) {
    * @param {import('simple-git').SimpleGit} git
    * @param {number} limit
    */
-  async function recentCommits(git, limit) {
+  async function recentCommits(git, limit, head = 'HEAD') {
     const raw = await git.raw([
-      'log', `--max-count=${limit}`, '--format=%H%x00%h%x00%s%x00%cr'
+      'log', `--max-count=${limit}`, '--format=%H%x00%h%x00%s%x00%cr', head, '--'
     ]);
 
     return raw
@@ -396,13 +485,6 @@ function createApp(options = {}) {
       });
   }
 
-  /**
-   * The commits of an open repository, newest first.
-   *
-   * Behind a session id like the file endpoints rather than taking a path:
-   * this reads history out of a repository, and the session is what says
-   * which repository the caller has already been granted.
-   */
   /**
    * Everything the compare pickers offer: branches, tags and recent commits.
    *
@@ -445,11 +527,18 @@ function createApp(options = {}) {
     };
 
     const current = await git.revparse(['--abbrev-ref', 'HEAD']).then(b => b.trim()).catch(() => null);
+
+    // The commits offered are the history of whatever is being compared, not
+    // always of the checkout: comparing main against feature/billing from a
+    // checkout of feature/auth should offer billing's commits to pick from.
+    const requested = typeof req.query.head === 'string' ? req.query.head.trim() : '';
+    const head = requested && looksLikeRef(requested) ? requested : 'HEAD';
+
     const [branches, remotes, tags, commits] = await Promise.all([
       refList('refs/heads', REF_LIST_LIMIT),
       refList('refs/remotes', REF_LIST_LIMIT),
       refList('refs/tags', REF_LIST_LIMIT),
-      recentCommits(git, COMMIT_LIST_LIMIT).catch(() => [])
+      recentCommits(git, COMMIT_LIST_LIMIT, head).catch(() => [])
     ]);
 
     res.json({
@@ -463,6 +552,77 @@ function createApp(options = {}) {
     });
   });
 
+  /**
+   * The commits a review can be narrowed to, one at a time or as a run.
+   *
+   * With a base: the commits the comparison is made of -- what `base..head`
+   * has -- oldest first, because a branch reads as a story in the order it
+   * was written, and stepping through it commit by commit is the point.
+   * Without one: the recent history of `head`, newest first, the way `git
+   * log` reads, because there is no story there, only "how far back".
+   *
+   * Each commit carries its full message. The subject is what fits in a
+   * list, but the body is often where the author explains the change, and a
+   * reviewer looking at one commit should not have to leave the tool to read
+   * why it was made.
+   *
+   * Records are split on %x1e rather than on newlines, because a commit body
+   * is made of newlines.
+   */
+  app.get('/api/log/:repoId', async (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+
+    const git = gitFactory(session.repoPath);
+    const pick = name => (typeof req.query[name] === 'string' ? req.query[name].trim() : '');
+    const head = pick('head') || 'HEAD';
+    const base = pick('base');
+
+    for (const ref of base ? [base, head] : [head]) {
+      if (!looksLikeRef(ref)) {
+        return res.status(400).json({ error: 'That does not look like a commit or branch.' });
+      }
+    }
+
+    try {
+      const range = base ? `${base}..${head}` : head;
+      const total = Number((await git.raw(['rev-list', '--count', range, '--'])).trim()) || 0;
+      const raw = await git.raw([
+        'log', `--max-count=${LOG_LIMIT}`, ...(base ? ['--reverse'] : []),
+        '--format=%H%x00%h%x00%s%x00%an%x00%cr%x00%P%x00%b%x1e', range, '--'
+      ]);
+
+      const commits = raw.split('\u001e').map(record => record.replace(/^\n/, '')).filter(Boolean).map(record => {
+        const [sha, short, subject, author, when, parents, body] = record.split('\u0000');
+        return {
+          sha, short, subject, author, when,
+          body: (body ?? '').trim(),
+          // A merge is shown against its first parent when reviewed alone --
+          // what it brought in -- and the list says it is one, because that
+          // diff can be surprisingly large.
+          merge: (parents ?? '').trim().split(/\s+/).filter(Boolean).length > 1
+        };
+      });
+
+      res.json({
+        order: base ? 'oldest-first' : 'newest-first',
+        total,
+        truncated: total > commits.length,
+        commits
+      });
+    } catch {
+      res.status(400).json({ error: `Could not read the history of "${base ? `${base}..${head}` : head}".` });
+    }
+  });
+
+  /**
+   * The commits of an open repository, newest first. Kept for 2.11 callers;
+   * the page itself uses /api/refs and /api/log.
+   *
+   * Behind a session id like the file endpoints rather than taking a path:
+   * this reads history out of a repository, and the session is what says
+   * which repository the caller has already been granted.
+   */
   app.get('/api/commits/:repoId', async (req, res) => {
     try {
       const session = requireSession(res, req.params.repoId);
@@ -608,7 +768,7 @@ function createApp(options = {}) {
       // Resolve to the root of the working tree before anything is keyed on
       // this path. A subdirectory passes `checkIsRepo()` quite happily and
       // then produces a file list whose diffs are all empty; see lib/repo.js.
-      const { base, head } = req.body ?? {};
+      const { base, head, commits: run } = req.body ?? {};
       const root = await repoRoot(repoPath, gitFactory);
       if (!root) {
         return res.status(400).json({ error: 'Not a valid git repository' });
@@ -621,7 +781,18 @@ function createApp(options = {}) {
       let range = null;
       let message;
 
-      if (base !== undefined && base !== null && `${base}`.trim() !== '') {
+      if (run && typeof run === 'object') {
+        // Commits themselves, one or a run: see resolveCommitRun.
+        try {
+          range = await resolveCommitRun(git, `${run.from ?? ''}`.trim(), `${run.to ?? run.from ?? ''}`.trim());
+        } catch (error) {
+          return res.status(400).json({ error: error.message });
+        }
+
+        files = await collectRangeChanges(git, range);
+        mode = 'range';
+        message = describeCommitRun(range, files.length);
+      } else if (base !== undefined && base !== null && `${base}`.trim() !== '') {
         // An explicit range. Nothing falls back to anything here: someone who
         // asked for x1..x3 and is silently shown their working tree instead
         // has been told a lie about what they are reviewing.