git-reviewer 2.9.1 → 2.10.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-310-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
@@ -294,7 +294,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 299 tests
+npm test              # 310 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.10.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,70 @@ 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');
+
+  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`;
+    document.getElementById('compareBase').value = shortSha(base);
+    return;
+  }
+
+  label.textContent = data.mode === 'lastCommit'
+    ? 'Reviewing the last commit'
+    : 'Reviewing uncommitted changes';
+  document.getElementById('compareBase').value = '';
+}
+
+/** 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 = '';
+  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 +210,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 +230,22 @@ async function loadRepo() {
       setRepoButton(data.repoPath);
     }
 
+    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 +1827,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,22 @@
       </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">
+        <label for="compareBase">Compare from</label>
+        <input
+          type="text"
+          id="compareBase"
+          placeholder="commit, tag or branch"
+          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,61 @@ 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;
+  }
+}

package/server.js

@@ -121,9 +121,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 +198,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 +207,92 @@ 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`;
+  }
+
   /** 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 +424,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 +432,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 +491,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 +583,7 @@ function createApp(options = {}) {
         repoPath: session.repoPath,
         lastUpdated: new Date().toISOString(),
         mode: session.mode,
+        range: session.range,
         comments: normalized
       };
 
@@ -535,7 +647,8 @@ function createApp(options = {}) {
         generatedAt,
         head,
         branch,
-        mode: session.mode
+        mode: session.mode,
+        range: session.range
       });
       const documentFilename = filename.replace(/\.txt$/, '.json');