git-reviewer 2.11.0 → 2.13.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-314-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-355-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 When an agent writes the code, reading it becomes the bottleneck — and the tool
@@ -141,34 +141,69 @@ 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
+### Comparing branches and commits
 
-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.
+Those defaults cover the common case with nothing to set up, but a branch you
+have worked on for a day is several commits deep, and the default scope only
+ever shows 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.
+**Compare branches** in the header opens the comparison your pull request would
+show. If the repository has an obvious base — `origin/main`, then `main`, then
+`master` or `develop` — it compares your current branch against it straight
+away; otherwise it asks. Remote branches come first because a local `main` that
+has not been pulled in a week is a quietly wrong base.
 
-The commit the range starts from is not itself included: "changes since x1"
-means everything after x1, the same as `x1..HEAD`.
+Both ends are pickers: **Base** and **Compare**, the same two words a pull
+request uses. Each lists branches, remote branches, tags and recent commits, so
+you do not have to go and find a SHA. **Other…** at the bottom of either takes
+anything else git understands — `HEAD~5`, a tag, a SHA from somewhere else. The
+⇄ button swaps them, which answers the other question: what has `main` got that
+my branch has not?
 
-The bar keeps saying how many commits the range covers, and it keeps saying it
-when there are no files:
+**It shows what the branch changes, not everything that differs.** If `main`
+has moved on since your branch was cut, a plain two-ended diff would include
+`main`'s newer work *reversed*, as though your branch had undone it. The
+comparison starts from where the two diverged instead, exactly as a pull
+request does, and says what it left out:
 
 ```
-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.
+main → feature/auth    3 commits · 2 files changed
+
+main has 1 newer commit that is not on feature/auth. It is left out: this shows
+only what feature/auth changes since the two diverged, as a pull request would.
 ```
 
-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".
+An empty comparison explains itself rather than showing a blank list. Two
+commits that add a file and then delete it produce no diff between the ends —
+correctly — and that reads as *"2 commits undo each other"*, not as *"nothing
+to review"*.
+
+#### Reviewing commit by commit
+
+Whenever the review is made of commits, the sidebar lists them above the files:
+the commits a comparison is made of, oldest first, or the branch's recent
+history when you are looking at its last commit.
+
+- **Click** a commit to review it on its own, with its full message above the
+  diff — often the only place the author says *why*.
+- **Shift-click** a second to review the run between them, both ends included.
+  From the last commit, shift-clicking three rows down is "the last three
+  commits"; inside a comparison, it skips the ones you have already read.
+- **`[`** and **`]`** step one commit older or newer, and **All commits** goes
+  back to the whole comparison.
+
+That is the same gesture a pull request's commit picker uses, for the same
+reasons: a large change reads better in the order it was written, and one
+commit of renames is easier to skip than to read around.
+
+A run has to be one unbroken line of history. To diff two points that are not
+— a commit on one branch against another branch — use **Compare**; its pickers
+list recent commits of whichever branch you are comparing, right after the
+local branches.
+
+Comments are kept when you switch between comparisons. One on a file that is
+not in the current view stays in the comments list, marked **Not in this
+view**, and is back in place whenever you open a view that includes the file.
 
 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
@@ -293,7 +328,11 @@ The UI is a client of this; nothing is hidden from you.
 | Endpoint | Purpose |
 |---|---|
 | `GET /api/health` | Liveness, plus the number of open sessions |
-| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files |
+| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files. Pass `base` (and optionally `head`) to compare two refs from their merge base, or `commits: { from, to }` to review one commit or an unbroken run of them, both ends included |
+| `GET /api/refs/:repoId` | Branches, remote branches, tags and recent commits, for choosing what to compare. `?head=` makes the commits those of another branch |
+| `GET /api/log/:repoId` | Commits with their messages: `?base=&head=` for a comparison's commits, oldest first, or `?head=` alone for recent history, newest first |
+| `GET /api/commits/:repoId` | Recent commits only; kept for callers of 2.11 |
+| `GET /api/alive` | Held open by the page; when the last one closes, a terminal run stops |
 | `GET /api/file/:repoId/:path` | The file's diff, as structured lines |
 | `GET /api/file-full/:repoId/:path` | Every line of the file, for context |
 | `POST /api/save-comments` | Persist the current comments |
@@ -323,7 +362,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 314 tests
+npm test              # 355 tests
 npm run test:watch
 npm run test:coverage
 ```

package/lib/agent.js

@@ -205,13 +205,44 @@ function describeScope({ repository, mode, range }) {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  if (mode === 'range' && range?.kind === 'commits') {
+    // Commits themselves, picked from a list. Both ends are *in* the review,
+    // which is the difference from a comparison and worth saying: an agent
+    // told "between A and B" would reasonably assume A's own changes were
+    // outside it.
+    if (range.first === range.last) {
+      return `Reviewed: commit ${range.last}${range.subject ? ` ("${range.subject}")` : ''} on its own, against its parent.`;
+    }
+    return `Reviewed: ${range.commits} commits, ${range.first} through ${range.last} inclusive, as a single combined diff.`;
+  }
+
   if (mode === 'range' && range) {
     // Both ends, and the count, because the count is the only thing that
     // distinguishes "one commit of work" from "nine" once the diff has been
     // 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.`;
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+    const commits = plural(range.commits, 'commit');
+
+    // Ranges saved before 2.12 carry neither names nor a merge base. Say what
+    // they can support and no more.
+    if (!range.from || !range.baseName || !range.headName) {
+      return `Reviewed: everything between ${range.base} and ${range.head} (${commits}), as a single combined diff.`;
+    }
+
+    const ends = `${range.baseName} \u2192 ${range.headName}`;
+    if (range.from === range.base) {
+      return `Reviewed: ${ends} (${range.base}..${range.head}), ${commits} as a single combined diff.`;
+    }
+
+    // Diverged. The agent needs the left-out half as much as the reviewed
+    // half: code on the base that differs from the head is not something the
+    // reviewer asked anyone to change, and an agent that "fixes" it has
+    // reverted someone else's work.
+    const behind = range.behind > 0
+      ? ` ${range.baseName} has ${plural(range.behind, 'newer commit')} that ${range.behind === 1 ? 'is' : 'are'} deliberately not part of this review; leave that code alone.`
+      : '';
+    return `Reviewed: what ${range.headName} changes since it diverged from ${range.baseName} (merge base ${range.from}, head ${range.head}), ${commits} as a single combined diff.${behind}`;
   }
 
   if (mode === 'lastCommit') {

package/lib/changes.js

@@ -191,12 +191,80 @@ function classifyCommitFile(file) {
  * @param {import('simple-git').DiffResult} diffSummary
  * @returns {ChangedFile[]}
  */
-function collectCommitChanges(diffSummary) {
+/**
+ * Read `git diff --name-status -z` into what git itself says happened to
+ * each path.
+ *
+ * This exists because `classifyCommitFile` above has to guess from line
+ * counts, and the guess is wrong for a large share of ordinary edits: a
+ * change that only adds lines to an existing file reads as `A`, and one that
+ * only removes lines reads as `D` -- a reviewer shown "deleted" on a file
+ * that lost one line has been told something false by the badge meant to
+ * orient them. Git knows the answer; ask it.
+ *
+ * `-z` rather than the default output because the default quotes and
+ * octal-escapes non-ASCII paths the same way `--stat` does, and those were
+ * #20's bug the first time. With `-z` every field is NUL-terminated and the
+ * path is raw bytes, so there is nothing to unquote.
+ *
+ * Renames and copies (`R100`, `C75`) carry two paths; the second is the one
+ * the file now lives at, which is the one the rest of the app keys on.
+ *
+ * @param {string} raw output of `git diff --name-status -z -M <from> <to>`
+ * @returns {Map<string, 'A'|'M'|'D'|'R'>} path -> status
+ */
+function parseNameStatus(raw) {
+  const statuses = new Map();
+  const fields = String(raw ?? '').split('\0');
+
+  for (let i = 0; i < fields.length; ) {
+    const code = fields[i];
+    if (!code) { i += 1; continue; }
+
+    const letter = code[0];
+    if (letter === 'R' || letter === 'C') {
+      const to = fields[i + 2];
+      // A copy is a new file that happens to resemble an old one; from the
+      // reviewer's side it is an addition.
+      if (to) statuses.set(to, letter === 'R' ? 'R' : 'A');
+      i += 3;
+      continue;
+    }
+
+    const path = fields[i + 1];
+    if (path) {
+      // T is a type change (a file became a symlink, or the reverse). The
+      // path still exists on both sides, so for review purposes it is a
+      // modification.
+      statuses.set(path, letter === 'A' || letter === 'D' ? letter : 'M');
+    }
+    i += 2;
+  }
+
+  return statuses;
+}
+
+/**
+ * The flat file list for a commit or range review.
+ *
+ * Paths still come from `diffSummary`, whose rename and quoting handling was
+ * earned the hard way (#20, #25, #64). Only the status letter comes from
+ * `statuses` when it is given -- which every caller in the server does. The
+ * count-based guess remains as the fallback for a caller that has nothing
+ * better, not as the answer.
+ *
+ * @param {import('simple-git').DiffResult} diffSummary
+ * @param {Map<string, string>} [statuses] from `parseNameStatus`
+ */
+function collectCommitChanges(diffSummary, statuses) {
   const files = diffSummary?.files ?? [];
   return files.map(file => {
     const { path, isRename } = parseCommitFilePath(file?.file);
-    const status = isRename ? 'R' : classifyCommitFile(file);
-    return { path, status };
+    if (isRename) return { path, status: 'R' };
+    if (file?.binary) return { path, status: 'B' };
+
+    const known = statuses?.get(path);
+    return { path, status: known ?? classifyCommitFile(file) };
   });
 }
 
@@ -205,5 +273,6 @@ module.exports = {
   collectCommitChanges,
   classifyCommitFile,
   unquoteGitPath,
-  parseCommitFilePath
+  parseCommitFilePath,
+  parseNameStatus
 };

package/package.json

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