git-reviewer 2.9.1 → 2.11.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-299-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-314-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,6 +141,35 @@ is nothing to configure:
 | Working directory clean | The last commit against its parent |
 | No commits yet | Every tracked and untracked file, as wholly new |
 
+### Reviewing further back than the last commit
+
+Those defaults cover the common case and nothing else needs setting up, but a
+branch you have been working on for a day is several commits deep, and the
+default scope only ever shows you the most recent one.
+
+**Changes since** in the header takes any earlier commit and reloads the review
+as a single combined diff up to `HEAD`. Pick one from the dropdown — recent
+commits by subject line and when they landed, so you do not have to go and find
+a SHA — or type a branch, a tag, or something like `HEAD~5` in the box beside
+it for anything the list does not reach.
+
+The commit the range starts from is not itself included: "changes since x1"
+means everything after x1, the same as `x1..HEAD`.
+
+The bar keeps saying how many commits the range covers, and it keeps saying it
+when there are no files:
+
+```
+Comparing 86b28f11 → 27668114 — 2 commits, shown as one combined diff
+2 commits, and no net change between the two ends — every change in them was
+undone again inside the range.
+```
+
+That is a real answer, not an empty screen. A file added in one commit and
+deleted in a later one is correctly absent from a diff of the two ends, and
+"no net change across 2 commits" is a different statement from "nothing to
+review".
+
 Modified, added, deleted, renamed, and binary files are all listed, each marked
 with its git status letter. Deleted lines are commentable too — the most useful
 review note is often about the code someone removed. A file deleted outright is
@@ -294,7 +323,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 299 tests
+npm test              # 314 tests
 npm run test:watch
 npm run test:coverage
 ```

package/lib/agent.js

@@ -50,7 +50,7 @@ const SCHEMA = 'code-review/v1';
  * @param {string|null} [args.mode]
  * @returns {ReviewDocument}
  */
-function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null }) {
+function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null, range = null }) {
   const grouped = groupByFile(comments);
 
   return {
@@ -63,6 +63,10 @@ function buildReviewDocument({ repoPath, comments, generatedAt, head = null, bra
       branch
     },
     mode,
+    // Omitted rather than null when there is no range, so `"range" in
+    // document` is a meaningful test -- the same rule the optional comment
+    // fields follow. A `working` review has no range and never will.
+    ...(range ? { range } : {}),
     summary: {
       comments: comments.length,
       files: grouped.length
@@ -194,13 +198,22 @@ function toAgentComment(comment, id) {
  * @param {ReviewDocument} document
  * @returns {string|null}
  */
-function describeScope({ repository, mode }) {
+function describeScope({ repository, mode, range }) {
   const at = repository.head ? ` (${repository.head})` : '';
 
   if (mode === 'working') {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  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
+    // flattened -- and an agent reading a flattened diff of nine commits
+    // should know that is what it is holding.
+    const commits = `${range.commits} commit${range.commits === 1 ? '' : 's'}`;
+    return `Reviewed: everything between ${range.base} and ${range.head} (${commits}), as a single combined diff.`;
+  }
+
   if (mode === 'lastCommit') {
     return repository.head
       ? `Reviewed: commit ${repository.head}, against its parent.`

package/lib/export.js

@@ -100,7 +100,7 @@ async function readGitPosition(repoPath) {
  *   records a different repository than the one asked for
  */
 async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
-  const { comments, mode } = await readSavedComments(reviewsDir, repoPath);
+  const { comments, mode, range } = await readSavedComments(reviewsDir, repoPath);
 
   if (comments.length === 0) throw new NoReviewError(repoPath);
 
@@ -121,7 +121,7 @@ async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
   // same object reference when no filter is given. `test/agent.test.js`
   // asserts that identity with `assert.equal`.
   const document = filterReviewDocument(
-    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode }),
+    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode, range }),
     { file }
   );
 

package/lib/sessions.js

@@ -11,9 +11,21 @@ const crypto = require('crypto');
  */
 
 /**
- * @typedef {'working'|'lastCommit'} ReviewMode
+ * @typedef {'working'|'lastCommit'|'range'} ReviewMode
  * `working` diffs the working tree against HEAD; `lastCommit` diffs HEAD
- * against its parent, which is what a clean tree falls back to.
+ * against its parent, which is what a clean tree falls back to; `range`
+ * diffs two refs the reviewer chose.
+ */
+
+/**
+ * @typedef {object} ReviewRange
+ * @property {string} base ref the review is measured from, already resolved
+ * @property {string} head ref the review is measured to, already resolved
+ * @property {number} commits how many commits separate them
+ *
+ * Present for every commit-based review, including `lastCommit`, which is
+ * just the range `HEAD~1..HEAD` under a name. `working` has no range: its
+ * head is the working tree, which is not a ref.
  */
 
 class SessionStore {
@@ -22,24 +34,25 @@ class SessionStore {
    */
   constructor(generateId = () => crypto.randomBytes(8).toString('hex')) {
     this.generateId = generateId;
-    /** @type {Map<string, {repoPath: string, mode: ReviewMode}>} */
+    /** @type {Map<string, {repoPath: string, mode: ReviewMode, range: ReviewRange|null}>} */
     this.sessions = new Map();
   }
 
   /**
    * @param {string} repoPath absolute path of the opened repository
    * @param {ReviewMode} mode
+   * @param {ReviewRange|null} [range] the two refs, for a commit-based review
    * @returns {string} the new session id
    */
-  create(repoPath, mode) {
+  create(repoPath, mode, range = null) {
     const repoId = this.generateId();
-    this.sessions.set(repoId, { repoPath, mode });
+    this.sessions.set(repoId, { repoPath, mode, range });
     return repoId;
   }
 
   /**
    * @param {string} repoId
-   * @returns {{repoPath: string, mode: ReviewMode}|undefined}
+   * @returns {{repoPath: string, mode: ReviewMode, range: ReviewRange|null}|undefined}
    */
   get(repoId) {
     return this.sessions.get(repoId);

package/lib/store.js

@@ -74,7 +74,7 @@ async function readJson(file) {
  *
  * @param {string} reviewsDir
  * @param {string} repoPath
- * @returns {Promise<{comments: object[], mode: string|null, adopted: boolean}>}
+ * @returns {Promise<{comments: object[], mode: string|null, range: object|null, adopted: boolean}>}
  *   `mode` is null for a file written before it was recorded -- there is
  *   nothing on disk that says what was compared, and guessing would be
  *   worse than admitting it.
@@ -90,15 +90,15 @@ async function readSavedComments(reviewsDir, repoPath) {
     if (!belongsTo(saved.repoPath, repoPath)) {
       throw new ReviewOwnershipError(repoPath, saved.repoPath);
     }
-    return { comments: saved.comments ?? [], mode: saved.mode ?? null, adopted: false };
+    return { comments: saved.comments ?? [], mode: saved.mode ?? null, range: saved.range ?? null, adopted: false };
   }
 
   const legacyName = legacyCommentsFilename(repoPath);
-  if (legacyName === commentsFilename(repoPath)) return { comments: [], mode: null, adopted: false };
+  if (legacyName === commentsFilename(repoPath)) return { comments: [], mode: null, range: null, adopted: false };
 
   const legacy = await readJson(path.join(reviewsDir, legacyName));
   if (legacy === null || !belongsTo(legacy.repoPath, repoPath)) {
-    return { comments: [], mode: null, adopted: false };
+    return { comments: [], mode: null, range: null, adopted: false };
   }
 
   // Move it under the new name so the next read is a plain hit and the old
@@ -110,7 +110,7 @@ async function readSavedComments(reviewsDir, repoPath) {
     /* the comments are already in hand; renaming is housekeeping */
   }
 
-  return { comments: legacy.comments ?? [], mode: legacy.mode ?? null, adopted: true };
+  return { comments: legacy.comments ?? [], mode: legacy.mode ?? null, range: legacy.range ?? null, adopted: true };
 }
 
 module.exports = { readSavedComments, ReviewOwnershipError, belongsTo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.9.1",
+  "version": "2.11.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

@@ -132,7 +132,129 @@ function calculateSimilarity(str1, str2) {
 }
 
 // Load local repository
-async function loadRepo() {
+/** Short form of a commit sha, for reading rather than for copying. */
+function shortSha(sha) {
+  return typeof sha === 'string' ? sha.slice(0, 8) : '';
+}
+
+/**
+ * Say what the review is of, above the files.
+ *
+ * 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".
+ *
+ * @param {{mode: string, range: ?{base: string, head: string, commits: number}}} data
+ */
+function renderScope(data) {
+  const bar = document.getElementById('scopeBar');
+  const label = document.getElementById('scopeLabel');
+  const reset = document.getElementById('scopeResetBtn');
+
+  bar.classList.remove('hidden');
+  reset.classList.toggle('hidden', data.mode !== 'range');
+
+  const select = document.getElementById('compareSelect');
+
+  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 : '';
+    return;
+  }
+
+  label.textContent = data.mode === 'lastCommit'
+    ? 'Reviewing the last commit'
+    : 'Reviewing uncommitted changes';
+  select.value = '';
+  document.getElementById('compareBase').value = '';
+}
+
+/**
+ * Fill the commit picker for the open repository.
+ *
+ * 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.
+ *
+ * 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.
+ */
+async function loadCommitOptions(repoId) {
+  const select = document.getElementById('compareSelect');
+
+  try {
+    const response = await fetch(`${API_BASE}/commits/${repoId}`);
+    if (!response.ok) return;
+
+    const { commits } = await response.json();
+    const options = commits.slice(1);
+
+    select.innerHTML = '';
+    if (options.length === 0) {
+      select.appendChild(new Option('No earlier commits', ''));
+      select.disabled = true;
+      return;
+    }
+
+    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 */
+  }
+}
+
+/** Compare from whatever was chosen in the picker. */
+function compareFromSelection() {
+  const base = document.getElementById('compareSelect').value;
+  if (!base) return;
+
+  document.getElementById('compareBase').value = '';
+  loadRepo({ base });
+}
+
+/** Reload the repository as a range starting at whatever was typed. */
+function compareFrom() {
+  const base = document.getElementById('compareBase').value.trim();
+
+  if (!base) {
+    showStatus('Enter a commit, tag or branch to compare from', 'error');
+    return;
+  }
+
+  loadRepo({ base });
+}
+
+/** Back to the default scope: uncommitted changes, or the last commit. */
+function resetScope() {
+  document.getElementById('compareBase').value = '';
+  document.getElementById('compareSelect').value = '';
+  loadRepo();
+}
+
+/**
+ * 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.
+ */
+async function loadRepo(scope = {}) {
   const repoPath = document.getElementById('repoPath').value.trim();
 
   if (!repoPath) {
@@ -147,7 +269,7 @@ async function loadRepo() {
     const response = await fetch(`${API_BASE}/load-repo`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ repoPath })
+      body: JSON.stringify(scope.base ? { repoPath, base: scope.base } : { repoPath })
     });
 
     const data = await response.json();
@@ -167,7 +289,25 @@ async function loadRepo() {
       setRepoButton(data.repoPath);
     }
 
+    // Before renderScope, which needs the options present to be able to
+    // select the current base among them.
+    await loadCommitOptions(data.repoId);
+    renderScope(data);
+
     if (data.files.length === 0) {
+      // A range with no files is a real answer, not a failure: every change
+      // in it was undone again before the far end. The server says so in
+      // `message`, and the scope bar above is still showing how many commits
+      // 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');
+        hidePicker();
+        displayFiles([]);
+        document.getElementById('loadBtn').disabled = false;
+        return;
+      }
+
       showStatus('No uncommitted changes found in the repository', 'error');
       document.getElementById('loadBtn').disabled = false;
       return;
@@ -1749,6 +1889,12 @@ document.addEventListener('DOMContentLoaded', () => {
     }
   });
 
+  document.getElementById('compareBase').addEventListener('keypress', (e) => {
+    if (e.key === 'Enter') {
+      compareFrom();
+    }
+  });
+
   // Initialize resize handle
   initResizeHandle();
 

package/public/index.html

@@ -54,6 +54,28 @@
       </div>
     </div>
     <div id="status" class="status"></div>
+
+    <div id="scopeBar" class="scope-bar hidden">
+      <span id="scopeLabel" class="scope-label"></span>
+      <div class="scope-compare">
+        <!-- "since", not "from": `base..HEAD` does not include base's own
+             changes, and a picker that says "compare from x1" invites the
+             reading that x1 is in the diff. -->
+        <label for="compareSelect">Changes since</label>
+        <select id="compareSelect" onchange="compareFromSelection()" aria-label="Review everything after this commit">
+          <option value="">Pick a commit…</option>
+        </select>
+        <input
+          type="text"
+          id="compareBase"
+          placeholder="or a branch, tag or ref"
+          spellcheck="false"
+          autocomplete="off"
+          value="">
+        <button id="compareBtn" onclick="compareFrom()">Compare</button>
+        <button id="scopeResetBtn" class="scope-reset hidden" onclick="resetScope()">Back to latest</button>
+      </div>
+    </div>
   </header>
 
   <div class="main-container">

package/public/style.css

@@ -1877,3 +1877,90 @@ button:disabled {
   color: #7a5d00;
   text-align: center;
 }
+
+/* What the review is of, and how to change it.
+ *
+ * Its own row under the status line rather than beside the repository
+ * controls: choosing a repository and choosing which of its commits to look
+ * at are two different decisions, and crowding them made the header read as
+ * one long form. */
+.scope-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 8px 16px;
+  margin-top: 8px;
+  padding: 8px 12px;
+  border-radius: 6px;
+  background: #f3f4f6;
+  border-left: 3px solid #6a737d;
+  font-size: 13px;
+}
+
+/* The scope reads as a sentence rather than a field label, because the case
+ * that matters most is "9 commits, and no net change" — which has to be
+ * legible as an explanation, not as a value. */
+.scope-label {
+  color: #24292e;
+  min-width: 0;
+}
+
+.scope-compare {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.scope-compare label {
+  color: #6a737d;
+  white-space: nowrap;
+}
+
+.scope-compare input {
+  width: 190px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+}
+
+.scope-reset {
+  background: transparent;
+  border: 1px solid #d1d5da;
+  color: #24292e;
+}
+
+@media (max-width: 720px) {
+  .scope-compare input {
+    width: 120px;
+  }
+}
+
+/* The picker carries the common case; the text box beside it carries
+ * everything else — a branch, a tag, `HEAD~5`, a sha from somewhere else.
+ * Both stay visible rather than one hiding behind a mode, because a control
+ * you cannot see is a feature people believe is missing. */
+.scope-compare select {
+  max-width: 320px;
+  font-size: 12px;
+  padding: 4px 6px;
+  border: 1px solid #d1d5da;
+  border-radius: 6px;
+  background: #fff;
+  color: #24292e;
+}
+
+.scope-compare select:disabled {
+  color: #6a737d;
+  background: #f3f4f6;
+}
+
+@media (max-width: 720px) {
+  .scope-compare {
+    flex-wrap: wrap;
+  }
+
+  .scope-compare select {
+    max-width: 100%;
+  }
+}

package/server.js

@@ -62,6 +62,12 @@ class FileNotFoundError extends Error {
  *   leaves before deciding it is not coming back.
  * @returns {import('express').Express}
  */
+// How far back the range picker offers to go. Long enough to cover the work
+// someone is plausibly still reviewing, short enough that the list is a list
+// rather than the whole history -- anything older is still reachable by
+// typing a ref, which is what the text box is for.
+const COMMIT_LIST_LIMIT = 30;
+
 function createApp(options = {}) {
   const {
     reviewsDir = resolveReviewsDir(),
@@ -121,9 +127,9 @@ function createApp(options = {}) {
     const git = gitFactory(session.repoPath);
     const absolutePath = resolveRepoFile(session.repoPath, filePath);
 
-    if (session.mode === 'lastCommit') {
+    if (session.range) {
       try {
-        return await git.show([`HEAD:${filePath}`]);
+        return await git.show([`${session.range.head}:${filePath}`]);
       } catch {
         return await fs.readFile(absolutePath, 'utf-8').catch(() => '');
       }
@@ -198,8 +204,8 @@ function createApp(options = {}) {
   }
 
   async function diffForFile(git, session, filePath) {
-    if (session.mode === 'lastCommit') {
-      return git.diff(['HEAD~1', 'HEAD', '--', filePath]);
+    if (session.range) {
+      return git.diff([session.range.base, session.range.head, '--', filePath]);
     }
     if (!(await hasCommits(git))) {
       return '';
@@ -207,6 +213,144 @@ function createApp(options = {}) {
     return git.diff(['HEAD', '--', filePath]);
   }
 
+  /**
+   * A ref safe to hand to git as an argument.
+   *
+   * simple-git passes arguments as an array rather than through a shell, so
+   * there is no quoting to get wrong -- but a value beginning with `-` is
+   * still read by git as an option rather than as a ref, and
+   * `--output=/somewhere` is a real thing to hand `git diff`. Refs do not
+   * begin with a dash, so refusing one costs nothing.
+   *
+   * @param {string} ref
+   * @returns {boolean}
+   */
+  function looksLikeRef(ref) {
+    return ref.length > 0 && ref.length <= 255 && !ref.startsWith('-');
+  }
+
+  /**
+   * Turn two refs into the range a review is of.
+   *
+   * Both are resolved to commit SHAs here, once, and the session carries
+   * those rather than the names. A branch that moves under a review in
+   * progress would otherwise change what the review is of halfway through,
+   * and the comments already written would silently be about a diff that no
+   * longer exists.
+   *
+   * @param {import('simple-git').SimpleGit} git
+   * @param {string} base
+   * @param {string} head
+   * @returns {Promise<import('./lib/sessions').ReviewRange>}
+   * @throws {Error} with a message meant for the page, when a ref will not resolve
+   */
+  async function resolveRange(git, base, head) {
+    for (const [label, ref] of [['base', base], ['head', head]]) {
+      if (!looksLikeRef(ref)) {
+        throw new Error(`That ${label} does not look like a commit or branch.`);
+      }
+    }
+
+    const resolve = async (label, ref) => {
+      try {
+        return (await git.revparse([`${ref}^{commit}`])).trim();
+      } catch {
+        throw new Error(`No commit or branch called "${ref}" in this repository.`);
+      }
+    };
+
+    const baseSha = await resolve('base', base);
+    const headSha = await resolve('head', head);
+
+    // `base..head` counts what head has and base does not, which is the
+    // number a reviewer means by "how many commits am I looking at". It is
+    // not symmetric, and it is not the same as the file count -- a range
+    // whose changes cancel out has commits and no files, which is the whole
+    // reason this number is reported.
+    const commits = Number(
+      (await git.raw(['rev-list', '--count', `${baseSha}..${headSha}`])).trim()
+    );
+
+    return { base: baseSha, head: headSha, commits: Number.isFinite(commits) ? commits : 0 };
+  }
+
+  /**
+   * What to tell the reviewer about a range they just opened.
+   *
+   * The empty case is the one that matters. `git diff x3 x5` over a file
+   * added in x4 and deleted in x5 is correctly empty, and an interface that
+   * renders that as "no changes" is saying something false about two commits
+   * of real work. So the commit count leads, and the absence of files is
+   * described rather than left as a blank screen.
+   *
+   * @param {import('./lib/sessions').ReviewRange} range
+   * @param {number} fileCount
+   * @returns {string}
+   */
+  function describeRange(range, fileCount) {
+    const commits = `${range.commits} commit${range.commits === 1 ? '' : 's'}`;
+
+    if (fileCount === 0) {
+      return range.commits === 0
+        ? 'Those two commits are the same, so there is nothing between them.'
+        : `${commits}, and no net change between the two ends — every change in them was undone again inside the range.`;
+    }
+
+    return `${commits}, ${fileCount} changed file${fileCount === 1 ? '' : 's'} between the two ends`;
+  }
+
+  /**
+   * Recent commits, so a range can be picked instead of typed.
+   *
+   * Nobody knows the SHA of the commit they want to review back to, and
+   * asking for one is asking the reviewer to go and run `git log` in another
+   * window to use a tool whose whole point is not having to.
+   *
+   * Each entry is what a person recognises a commit by -- the subject line
+   * and when it landed -- with the SHA carried alongside rather than being
+   * the thing they have to read.
+   *
+   * `%x00` separates the fields because a commit subject can contain
+   * anything a person can type, including whatever delimiter looked safe.
+   *
+   * @param {import('simple-git').SimpleGit} git
+   * @param {number} limit
+   */
+  async function recentCommits(git, limit) {
+    const raw = await git.raw([
+      'log', `--max-count=${limit}`, '--format=%H%x00%h%x00%s%x00%cr'
+    ]);
+
+    return raw
+      .split('\n')
+      .filter(line => line.trim() !== '')
+      .map(line => {
+        const [sha, short, subject, when] = line.split('\u0000');
+        return { sha, short, subject, when };
+      });
+  }
+
+  /**
+   * 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.
+   */
+  app.get('/api/commits/:repoId', async (req, res) => {
+    try {
+      const session = requireSession(res, req.params.repoId);
+      if (!session) return;
+
+      const commits = await recentCommits(gitFactory(session.repoPath), COMMIT_LIST_LIMIT);
+      res.json({ commits });
+    } catch (error) {
+      // A repository with no commits is not an error, it is an empty list.
+      console.error('Commit list error:', error.message);
+      res.json({ commits: [] });
+    }
+  });
+
   /** Liveness probe, and a count of how many repositories are open. */
   app.get('/api/health', (req, res) => {
     res.json({ status: 'ok', sessions: sessions.size });
@@ -338,6 +482,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 root = await repoRoot(repoPath, gitFactory);
       if (!root) {
         return res.status(400).json({ error: 'Not a valid git repository' });
@@ -345,27 +490,51 @@ function createApp(options = {}) {
 
       const git = gitFactory(root);
 
-      let files = collectWorkingChanges(await git.status());
-      let mode = 'working';
-      let message = `Found ${files.length} changed file(s)`;
+      let files;
+      let mode;
+      let range = null;
+      let message;
 
-      // A clean tree has nothing to review, so fall back to the last commit.
-      if (files.length === 0) {
+      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.
         try {
-          const commitFiles = collectCommitChanges(await git.diffSummary(['HEAD~1', 'HEAD']));
-          if (commitFiles.length > 0) {
-            files = commitFiles;
-            mode = 'lastCommit';
-            message = `No working directory changes. Loaded last commit with ${files.length} changed file(s)`;
-          }
+          range = await resolveRange(git, `${base}`.trim(), `${head ?? 'HEAD'}`.trim());
         } catch (error) {
-          // A repository with no commits, or only one, has no parent to diff
-          // against. An empty file list is the correct answer there.
-          console.error('Error loading last commit:', error.message);
+          return res.status(400).json({ error: error.message });
+        }
+
+        files = collectCommitChanges(await git.diffSummary([range.base, range.head]));
+        mode = 'range';
+        message = describeRange(range, files.length);
+      } else {
+        files = collectWorkingChanges(await git.status());
+        mode = 'working';
+        message = `Found ${files.length} changed file(s)`;
+
+        // A clean tree has nothing to review, so fall back to the last commit.
+        if (files.length === 0) {
+          try {
+            const lastCommit = await resolveRange(git, 'HEAD~1', 'HEAD');
+            const commitFiles = collectCommitChanges(
+              await git.diffSummary([lastCommit.base, lastCommit.head])
+            );
+            if (commitFiles.length > 0) {
+              files = commitFiles;
+              mode = 'lastCommit';
+              range = lastCommit;
+              message = `No working directory changes. Loaded last commit with ${files.length} changed file(s)`;
+            }
+          } catch (error) {
+            // A repository with no commits, or only one, has no parent to diff
+            // against. An empty file list is the correct answer there.
+            console.error('Error loading last commit:', error.message);
+          }
         }
       }
 
-      const repoId = sessions.create(root, mode);
+      const repoId = sessions.create(root, mode, range);
       // stderr, not stdout. `reviewer | claude -p ...` puts the finished
       // review on stdout, and anything else written there lands in the middle
       // of it. Progress is for the person watching; stdout is for the pipe.
@@ -380,7 +549,7 @@ function createApp(options = {}) {
 
       // `repoPath` in the response is the resolved root, not what was asked
       // for, so the page can show which repository it actually opened.
-      res.json({ repoId, files, repoPath: root, mode, message });
+      res.json({ repoId, files, repoPath: root, mode, range, message });
     } catch (error) {
       console.error('Load repo error:', error);
       res.status(500).json({ error: error.message });
@@ -472,6 +641,7 @@ function createApp(options = {}) {
         repoPath: session.repoPath,
         lastUpdated: new Date().toISOString(),
         mode: session.mode,
+        range: session.range,
         comments: normalized
       };
 
@@ -535,7 +705,8 @@ function createApp(options = {}) {
         generatedAt,
         head,
         branch,
-        mode: session.mode
+        mode: session.mode,
+        range: session.range
       });
       const documentFilename = filename.replace(/\.txt$/, '.json');