git-reviewer 2.11.0 → 2.13.0

package/public/app.js

@@ -137,122 +137,631 @@ function shortSha(sha) {
   return typeof sha === 'string' ? sha.slice(0, 8) : '';
 }
 
+/** A full sha is shortened for display; a branch or tag name is left alone. */
+function displayRef(ref) {
+  return /^[0-9a-f]{40}$/i.test(ref ?? '') ? shortSha(ref) : (ref ?? '');
+}
+
+/** `n thing` or `n things`, instead of the `thing(s)` that reads like a form. */
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+// What the compare pickers can offer, from /api/refs. Refetched on every
+// load, because a comparison opens a new session and branches move.
+let currentRefs = null;
+
+// The "type something else" choice at the foot of either picker.
+const OTHER_REF = '__other__';
+
+const PICKERS = {
+  base: { select: 'compareBaseSelect', other: 'compareBaseOther' },
+  head: { select: 'compareHeadSelect', other: 'compareHeadOther' }
+};
+
+/**
+ * Fetch the branches, tags and commits the pickers offer, and fill both.
+ *
+ * A failure leaves both pickers with only "Other…" in them, which still
+ * works; a repository whose refs will not list is not a reason to refuse to
+ * compare it.
+ */
+async function loadRefs(repoId, head) {
+  try {
+    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;
+  }
+  fillPicker('base');
+  fillPicker('head');
+}
+
+/**
+ * Fill one picker, grouped the way people look for things.
+ *
+ * Branches first, because "my branch against main" is the comparison people
+ * reach for. Every label goes in through `new Option`, which sets text, not
+ * markup: branch names and commit subjects come from whatever repository is
+ * open, and a ref name may legally contain `<` and `>`.
+ */
+function fillPicker(end) {
+  const select = document.getElementById(PICKERS[end].select);
+  const refs = currentRefs;
+  select.innerHTML = '';
+
+  const placeholder = new Option(end === 'base' ? 'Choose a base…' : 'Choose what to compare…', '');
+  placeholder.disabled = true;
+  select.appendChild(placeholder);
+
+  const group = (label, options) => {
+    if (options.length === 0) return;
+    const optgroup = document.createElement('optgroup');
+    optgroup.label = label;
+    options.forEach(option => optgroup.appendChild(option));
+    select.appendChild(optgroup);
+  };
+
+  if (refs) {
+    group('Branches', refs.branches.map(branch => new Option(
+      `${branch.name}${branch.name === refs.current ? ' (current)' : ''}  ·  ${branch.when}`,
+      branch.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(
+      '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));
+  select.value = '';
+}
+
+/**
+ * Point a picker at a ref, by name if it is offered, by sha if the name is
+ * not but the commit is, and otherwise through "Other…" with the text shown.
+ *
+ * A range opened by typing `HEAD~2` resolves to a commit that may well be in
+ * the list; showing it selected there is more useful than a picker stuck on
+ * "Other" around a value that is also sitting three rows down.
+ */
+function selectRef(end, name, sha) {
+  const select = document.getElementById(PICKERS[end].select);
+  const other = document.getElementById(PICKERS[end].other);
+  const offered = value => [...select.options].some(option => option.value === value);
+
+  if (name && offered(name)) {
+    select.value = name;
+  } else if (sha && offered(sha)) {
+    select.value = sha;
+  } else if (name || sha) {
+    select.value = OTHER_REF;
+    other.value = name || displayRef(sha);
+    other.classList.remove('hidden');
+    return;
+  } else {
+    select.value = '';
+  }
+  other.classList.add('hidden');
+  other.value = '';
+}
+
+/** The ref one end of the comparison currently names, or '' if none yet. */
+function pickedRef(end) {
+  const select = document.getElementById(PICKERS[end].select);
+  return select.value === OTHER_REF
+    ? document.getElementById(PICKERS[end].other).value.trim()
+    : select.value;
+}
+
+/** Either picker changed: compare as soon as both ends are known. */
+function onPickerChange(end) {
+  const select = document.getElementById(PICKERS[end].select);
+  const other = document.getElementById(PICKERS[end].other);
+
+  if (select.value === OTHER_REF) {
+    other.classList.remove('hidden');
+    other.focus();
+    return; // Enter in the box compares; see the listeners in DOMContentLoaded.
+  }
+
+  other.classList.add('hidden');
+  compareNow();
+}
+
+function compareNow() {
+  const base = pickedRef('base');
+  const head = pickedRef('head');
+  if (base && head) loadRepo({ base, head });
+}
+
+/** Reverse the comparison: "what does main have that my branch does not". */
+function swapCompare() {
+  const base = pickedRef('base');
+  const head = pickedRef('head');
+  if (base && head) loadRepo({ base: head, head: base });
+}
+
+/**
+ * The base most people mean, if the repository makes it obvious.
+ *
+ * The remote comes first: a local `main` that has not been pulled in a week
+ * is a quietly wrong base, and `origin/main` is what the pull request will be
+ * measured against. Never the branch you are on -- comparing a branch with
+ * itself is always empty, and offering it as a default would make the first
+ * click of the feature look broken.
+ */
+function defaultBase() {
+  const refs = currentRefs;
+  if (!refs) return null;
+
+  const known = new Set([...refs.branches, ...refs.remotes].map(ref => ref.name));
+  const candidates = ['origin/main', 'main', 'origin/master', 'master', 'origin/develop', 'develop'];
+  return candidates.find(name => known.has(name) && name !== refs.current) ?? null;
+}
+
+/**
+ * Open the compare row. With an obvious base, compare straight away: one
+ * click to the view a pull request would give you. Without one, show the
+ * pickers and wait -- a guessed comparison nobody asked for is worse than
+ * asking.
+ */
+function openCompare() {
+  document.getElementById('compareRow').classList.remove('hidden');
+  const head = currentRefs?.current ?? 'HEAD';
+  const base = defaultBase();
+
+  if (base) {
+    loadRepo({ base, head });
+    return;
+  }
+
+  selectRef('base', null, null);
+  selectRef('head', head, null);
+  document.getElementById('compareToggle').classList.add('hidden');
+  document.getElementById('scopeResetBtn').classList.remove('hidden');
+  document.getElementById(PICKERS.base.select).focus();
+}
+
+/** Back to the default scope: uncommitted changes, or the last commit. */
+function resetScope() {
+  document.getElementById('compareRow').classList.add('hidden');
+  loadRepo();
+}
+
 /**
- * Say what the review is of, above the files.
+ * Say what the review is of, in the names the reviewer used.
  *
- * The empty-range case is the reason this exists. `git diff x3 x5` over work
- * that was added and then removed is correctly empty, and a file list showing
- * nothing is indistinguishable from a repository with nothing to review. The
- * commit count stays on screen so that an empty list reads as "9 commits, no
- * net change" rather than as "nothing happened".
+ * Built from DOM nodes rather than markup: branch names are chosen by
+ * whoever made the repository, and one may legally contain `<`.
  *
- * @param {{mode: string, range: ?{base: string, head: string, commits: number}}} data
+ * @param {{mode: string, range: ?object, files: object[]}} data
  */
 function renderScope(data) {
   const bar = document.getElementById('scopeBar');
   const label = document.getElementById('scopeLabel');
+  const meta = document.getElementById('scopeMeta');
+  const note = document.getElementById('scopeNote');
+  const row = document.getElementById('compareRow');
+  const toggle = document.getElementById('compareToggle');
   const reset = document.getElementById('scopeResetBtn');
 
+  const strong = text => {
+    const el = document.createElement('strong');
+    el.textContent = text;
+    return el;
+  };
+  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');
-  reset.classList.toggle('hidden', data.mode !== 'range');
+  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));
+    }
 
-  const select = document.getElementById('compareSelect');
+    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 { base, head, commits } = data.range;
-    label.textContent =
-      `Comparing ${shortSha(base)} \u2192 ${shortSha(head)} \u2014 ` +
-      `${commits} commit${commits === 1 ? '' : 's'}, shown as one combined diff`;
-    // Only if the base is one of the offered commits. A range opened by
-    // typing `HEAD~5` or a branch name has no matching option, and leaving
-    // the picker on its placeholder is honest -- the scope bar above already
-    // says exactly what is being compared.
-    select.value = [...select.options].some(option => option.value === base) ? base : '';
+    const range = data.range;
+    const base = displayRef(range.baseName ?? range.base);
+    const head = displayRef(range.headName ?? range.head);
+    const files = data.files.length;
+
+    label.append(strong(base), ' → ', strong(head));
+    meta.textContent = files > 0
+      ? `${plural(range.commits, 'commit')} · ${plural(files, 'file')} changed`
+      : `${plural(range.commits, 'commit')} · no files differ`;
+
+    // The empty cases first: they are the ones that need explaining, and an
+    // empty file list with no explanation reads as the tool having failed.
+    if (files === 0 && range.commits === 0) {
+      setNote(range.behind > 0
+        ? `${head} has nothing that ${base} does not already have. Try swapping them to see what ${base} adds.`
+        : `${base} and ${head} are the same commit, so there is nothing between them.`);
+    } else if (files === 0) {
+      setNote(`Those ${plural(range.commits, 'commit')} undo each other: every change in them was reverted again before ${head}, so there is no difference left to review.`);
+    } else if (range.behind > 0) {
+      // The merge-base diff leaves these out on purpose, the way a pull
+      // request does. Say so, or someone goes looking for main's change and
+      // concludes the tool lost it.
+      setNote(`${base} has ${plural(range.behind, 'newer commit')} that ${range.behind === 1 ? 'is' : 'are'} not on ${head}. ${range.behind === 1 ? 'It is' : 'They are'} left out: this shows only what ${head} changes since the two diverged, as a pull request would.`);
+    } else {
+      setNote(null);
+    }
+
+    row.classList.remove('hidden');
+    selectRef('base', range.baseName, range.base);
+    selectRef('head', range.headName, range.head);
+    toggle.classList.add('hidden');
+    reset.classList.remove('hidden');
     return;
   }
 
-  label.textContent = data.mode === 'lastCommit'
-    ? 'Reviewing the last commit'
-    : 'Reviewing uncommitted changes';
-  select.value = '';
-  document.getElementById('compareBase').value = '';
+  if (data.mode === 'lastCommit') {
+    label.append('Last commit');
+    if (branch) label.append(' on ', strong(branch));
+    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);
+  }
+
+  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;
 }
 
 /**
- * Fill the commit picker for the open repository.
+ * "3 hours ago" as "3h", for a list where the subject needs the width.
  *
- * The newest commit is deliberately not offered. "Changes since HEAD" is
- * either nothing or the working tree depending on how you squint, and both
- * of those are already what "Back to latest" gives you -- so listing it
- * would be offering a choice that cannot do anything useful.
+ * 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.
  *
- * A failure here is silent on purpose: the text box next to it still works,
- * and a repository whose history will not list is not a reason to refuse to
- * review it.
+ * @param {string} when git's %cr, e.g. "3 weeks ago" or "1 year, 2 months ago"
  */
-async function loadCommitOptions(repoId) {
-  const select = document.getElementById('compareSelect');
+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}/commits/${repoId}`);
-    if (!response.ok) return;
+    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;
+  }
+}
 
-    const { commits } = await response.json();
-    const options = commits.slice(1);
+/**
+ * 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;
+  }
 
-    select.innerHTML = '';
-    if (options.length === 0) {
-      select.appendChild(new Option('No earlier commits', ''));
-      select.disabled = true;
-      return;
-    }
+  commitAnchor = null;
+  commitSelection = null;
 
-    select.disabled = false;
-    select.appendChild(new Option('Pick a commit…', ''));
-    for (const commit of options) {
-      // The subject is what a person recognises; the sha is there to
-      // disambiguate two commits with the same message, which is common
-      // enough in a branch that has been rebased.
-      select.appendChild(new Option(`${commit.short} · ${commit.subject} · ${commit.when}`, commit.sha));
-    }
-  } catch {
-    /* the text box beside it is the fallback */
+  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;
   }
 }
 
-/** Compare from whatever was chosen in the picker. */
-function compareFromSelection() {
-  const base = document.getElementById('compareSelect').value;
-  if (!base) return;
+/** 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.`
+    : '';
 
-  document.getElementById('compareBase').value = '';
-  loadRepo({ base });
+  // 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' });
 }
 
-/** Reload the repository as a range starting at whatever was typed. */
-function compareFrom() {
-  const base = document.getElementById('compareBase').value.trim();
+/**
+ * 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 (!base) {
-    showStatus('Enter a commit, tag or branch to compare from', 'error');
+  if (extend && commitAnchor) {
+    const run = orderedRun(chronologicalCommits(commitContext), commitAnchor, sha);
+    if (run) loadRepo({ commits: { from: run[0], to: run[1] } });
     return;
   }
 
-  loadRepo({ base });
+  commitAnchor = sha;
+  loadRepo({ commits: { from: sha, to: sha } });
 }
 
-/** Back to the default scope: uncommitted changes, or the last commit. */
-function resetScope() {
-  document.getElementById('compareBase').value = '';
-  document.getElementById('compareSelect').value = '';
-  loadRepo();
+/** 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;
+  currentDiffLines = [];
+  document.getElementById('codeSection').classList.add('hidden');
+  document.getElementById('currentFile').textContent = '';
+}
+
+/** What the file list says when a comparison has no files in it. */
+function showEmptyFileList(message) {
+  const filesList = document.getElementById('filesList');
+  const empty = document.createElement('div');
+  empty.className = 'files-empty';
+  empty.textContent = message;
+  filesList.replaceChildren(empty);
 }
 
 /**
  * Load a repository, optionally as a range between two commits.
  *
- * @param {{base?: string}} [scope] omit for the default: uncommitted changes,
- *   falling back to the last commit on a clean tree.
+ * @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();
@@ -269,7 +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 } : { 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();
@@ -289,10 +802,14 @@ async function loadRepo(scope = {}) {
       setRepoButton(data.repoPath);
     }
 
-    // Before renderScope, which needs the options present to be able to
-    // select the current base among them.
-    await loadCommitOptions(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
@@ -301,9 +818,20 @@ async function loadRepo(scope = {}) {
       // that covers -- so this is information, not an error, and it must not
       // be dressed as one.
       if (data.mode === 'range') {
-        showStatus(data.message, 'success');
+        // The scope bar is already explaining this; a status line repeating
+        // it underneath is two bars saying one thing.
+        clearStatus();
         hidePicker();
         displayFiles([]);
+        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.
+        clearCodePane();
         document.getElementById('loadBtn').disabled = false;
         return;
       }
@@ -313,9 +841,15 @@ async function loadRepo(scope = {}) {
       return;
     }
 
-    showStatus(data.message, 'success');
+    // The scope bar above says what was loaded, in more useful terms than
+    // this line did ("Found 3 changed file(s)"), so there is nothing left
+    // for the status line to add on success.
+    clearStatus();
     hidePicker();
     displayFiles(data.files);
+    // Which comments are in view depends on which files are, so the sidebar
+    // is redrawn for every new scope, not only when saved comments arrive.
+    updateCommentsSidebar();
 
     // Load saved comments
     const savedComments = await loadCommentsFromBackend();
@@ -335,7 +869,7 @@ async function loadRepo(scope = {}) {
       // Show comments sidebar immediately
       updateCommentsSidebar();
 
-      showStatus(`${data.message} - Loaded ${savedComments.length} saved comment(s)`, 'success');
+      showStatus(`Picked up ${plural(savedComments.length, 'saved comment')} from last time.`, 'success');
     }
 
     // Open something. A loaded repository used to sit behind an empty pane
@@ -362,6 +896,15 @@ async function loadRepo(scope = {}) {
 }
 
 // Display list of changed files
+/** What each status letter means, for the badge's tooltip and screen readers. */
+const FILE_STATUS_NAMES = {
+  A: 'Added',
+  M: 'Modified',
+  D: 'Deleted',
+  R: 'Renamed',
+  B: 'Binary'
+};
+
 function fileStatusClass(status) {
   switch (status) {
     case 'A': return 'file-status-added';
@@ -396,7 +939,12 @@ function displayFiles(files) {
       ? `${escapeHtml(path)}/<span class="filename">${escapeHtml(filename)}</span>`
       : `<span class="filename">${escapeHtml(filename)}</span>`;
     const statusClass = fileStatusClass(status);
-    const statusBadge = `<span class="file-status ${statusClass}">${status}</span>`;
+    // One letter is git's vocabulary, not everyone's. The name rides along as
+    // a tooltip and as the accessible label, so "D" is never the only thing
+    // saying that a file is gone. `status` is one of five letters the server
+    // produces, and escaped anyway: it is data that ends up in markup.
+    const statusName = FILE_STATUS_NAMES[status] ?? 'Changed';
+    const statusBadge = `<span class="file-status ${statusClass}" title="${statusName}" aria-label="${statusName}">${escapeHtml(status)}</span>`;
 
     // The row used to carry the file name itself, inside a string literal
     // inside the attribute the browser evaluates as JavaScript. A name with a
@@ -1387,10 +1935,19 @@ function resetApp() {
 // Show status message
 function showStatus(message, type) {
   const statusEl = document.getElementById('status');
-  statusEl.textContent = 'Status: ' + message;
+  // No "Status:" prefix. The element is role="status", which is what tells a
+  // screen reader what it is; sighted readers could already see that.
+  statusEl.textContent = message;
   statusEl.className = `status ${type}`;
 }
 
+/** Hide the status line, when something else on screen is already saying it. */
+function clearStatus() {
+  const statusEl = document.getElementById('status');
+  statusEl.textContent = '';
+  statusEl.className = 'status hidden';
+}
+
 // Track if we're in full context mode
 let isFullContextMode = false;
 let storedFullFileLines = null;
@@ -1701,14 +2258,24 @@ function updateCommentsSidebar() {
         // anyway. A comment's identity here is its position in `comments`,
         // and that is a number. See #46.
         const commentIndex = comments.indexOf(comment);
+        // A comment is kept across comparisons -- switch from main -> feature
+        // back to the last commit and a note on a file only the branch
+        // touched is still yours. It just is not on screen, and a sidebar
+        // entry that looks attached but does nothing when clicked reads as
+        // lost. So it says where it stands.
+        const elsewhere = !currentFiles.some(f => f.path === file);
+        const elsewhereHtml = elsewhere
+          ? '<div class="comment-item-elsewhere-note">Not in this view</div>'
+          : '';
         html += `
-          <div class="comment-item">
+          <div class="comment-item${elsewhere ? ' comment-item-elsewhere' : ''}">
             <button class="comment-item-delete" onclick="event.stopPropagation(); deleteCommentFromSidebar(${Number(commentIndex)})" title="Delete comment">×</button>
             <div class="comment-item-content" onclick="jumpToComment(${Number(commentIndex)})">
               <div class="comment-item-file">${escapeHtml(file)}</div>
               <div class="comment-item-line">Line ${comment.line}</div>
               <div class="comment-item-text">${escapeHtml(comment.text)}</div>
               ${selectedHtml}
+              ${elsewhereHtml}
             </div>
           </div>
         `;
@@ -1748,7 +2315,17 @@ function jumpToComment(commentIndex) {
 
   // Find the file index
   const fileIndex = currentFiles.findIndex(f => f.path === file);
-  if (fileIndex === -1) return;
+  if (fileIndex === -1) {
+    // This used to return without a word, so clicking a comment did nothing
+    // and looked broken. The comment is safe; the file is just not part of
+    // what is being compared right now.
+    showStatus(
+      `${file} is not in the files you are looking at now, so this comment cannot be shown in place. ` +
+      'It is kept, and will be back in place in any view that includes that file.',
+      'loading'
+    );
+    return;
+  }
 
   // Load the file
   loadFile(file, fileIndex).then(() => {
@@ -1839,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;
   }
 
@@ -1851,6 +2432,8 @@ function getKeyboardShortcut(key, targetTagName, modifiers = {}) {
     'n': 'nextComment',
     'p': 'prevComment',
     'c': 'commentFocus',
+    '[': 'prevCommit',
+    ']': 'nextCommit',
     '?': 'help'
   };
 
@@ -1889,11 +2472,32 @@ document.addEventListener('DOMContentLoaded', () => {
     }
   });
 
-  document.getElementById('compareBase').addEventListener('keypress', (e) => {
-    if (e.key === 'Enter') {
-      compareFrom();
-    }
+  // 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') {
+        compareNow();
+      }
+    });
+  }
 
   // Initialize resize handle
   initResizeHandle();
@@ -1918,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();