git-reviewer 2.13.1 → 2.14.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-359-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-372-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
@@ -77,6 +77,7 @@ git reviewer export [repository] [--format json|prompt]
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --staged      Review only staged changes (HEAD vs index)
   -f, --format <f>  Export format: json (default) or prompt
   -h, --help        Show help
   -v, --version     Show the version
@@ -91,6 +92,15 @@ git reviewer . --port 8080  # somewhere other than 4500
 
 Two at once is fine — the second one finds its own port.
 
+Use `git reviewer --staged` to review what the next commit would contain.
+The file list, diff and full context come from the index, so edits made after
+`git add` stay out of the view. An empty index comparison stays empty; it does
+not fall back to the last commit. The scope bar and exported review identify
+this as a staged review. The default command still shows all working-tree
+changes. As with the default view, reload after changing what is staged. Saved comments
+are shared between views and may refer to code outside the current comparison;
+check their anchors before applying them.
+
 ### When you are not standing in a repository
 
 The page opens on a picker rather than on an empty box:
@@ -372,7 +382,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 359 tests
+npm test              # 372 tests
 npm run test:watch
 npm run test:coverage
 ```
@@ -399,7 +409,7 @@ temporary directory. The HTTP tests do not stub git: each one builds a real
 repository in a temp directory and runs real `git` against it, because diff
 parsing is exactly where a stub would be wrong in the same way the code is.
 
-Tests run on Linux and macOS across Node 18, 20, and 22. See
+Tests run on Linux, macOS and Windows across Node 18, 20, and 22. See
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Tech
@@ -423,11 +433,18 @@ The ones most likely to change how the tool feels:
 - [#2](https://github.com/dheerajjha/reviewer/issues/2) — give comments a state, so a review can be worked through and marked off
 - [#3](https://github.com/dheerajjha/reviewer/issues/3) — report whether each anchor still matches the file
 - [#4](https://github.com/dheerajjha/reviewer/issues/4) — expose the review over MCP, so an agent works through it interactively
-- [#6](https://github.com/dheerajjha/reviewer/issues/6) — review a commit range, not just the working tree
+- [#6](https://github.com/dheerajjha/reviewer/issues/6) — open straight into a comparison from the command line, `git reviewer --range main...HEAD`
 
 [CONTRIBUTING.md](CONTRIBUTING.md) covers the setup and what a good change looks
 like here.
 
+## Related
+
+[margins](https://github.com/dheerajjha/margins) is its sibling for notes rather
+than diffs: `margins` in a folder of markdown opens it in the browser, with a
+file tree, `[[wikilinks]]` and backlinks, search, and editing with a live
+preview. `npm install -g margins`.
+
 ## License
 
 [MIT](LICENSE) © Dheeraj Jha

package/bin/reviewer.js

@@ -250,7 +250,7 @@ async function main() {
     options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
     { onReviewSubmitted, handoff: handingOff, onIdle }
   );
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
+  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath, options.staged);
 
   note(`\n  Code Reviewer  ${url}`);
   if (repoPath) note(`  reviewing      ${repoPath}`);

package/lib/agent.js

@@ -22,7 +22,7 @@ const SCHEMA = 'code-review/v1';
  * @property {string} schema
  * @property {string} generatedAt ISO 8601
  * @property {{path: string, name: string, head: string|null, branch: string|null}} repository
- * @property {'working'|'lastCommit'|null} mode
+ * @property {'working'|'staged'|'lastCommit'|'range'|null} mode
  * @property {{comments: number, files: number}} summary
  * @property {AgentComment[]} comments
  */
@@ -205,6 +205,10 @@ function describeScope({ repository, mode, range }) {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  if (mode === 'staged') {
+    return 'Comparison: staged changes in the index, against HEAD. Saved comments are shared between review views and may refer to changes outside this comparison; check their anchors before applying them.';
+  }
+
   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

package/lib/changes.js

@@ -268,7 +268,24 @@ function collectCommitChanges(diffSummary, statuses) {
   });
 }
 
+/**
+ * Files in the next commit, including their index status rather than any
+ * later working-tree edits. Omitting HEAD also works before the first commit.
+ * @param {import('simple-git').SimpleGit} git
+ */
+async function collectStagedChanges(git) {
+  if (await git.raw(['ls-files', '--unmerged', '-z'])) {
+    throw new Error('Resolve merge conflicts before reviewing staged changes.');
+  }
+  const [summary, raw] = await Promise.all([
+    git.diffSummary(['--cached']),
+    git.raw(['diff', '--cached', '--name-status', '-z', '-M'])
+  ]);
+  return collectCommitChanges(summary, parseNameStatus(raw));
+}
+
 module.exports = {
+  collectStagedChanges,
   collectWorkingChanges,
   collectCommitChanges,
   classifyCommitFile,

package/lib/cli.js

@@ -43,6 +43,7 @@ Options:
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --staged      Review only staged changes (HEAD vs index)
   -f, --format <f>  Export format: json (default) or prompt
       --file <path> Export comments for one repo-relative file
   -h, --help        Show this help
@@ -83,6 +84,7 @@ class UsageError extends Error {
  * @property {string|null} repoPath absolute path, or null when not given
  * @property {number|null} port explicit port, or null to use the default
  * @property {boolean} open whether to launch a browser
+ * @property {boolean} staged whether to review only the index
  * @property {'json'|'prompt'} format for `export`
  * @property {string|null} file repo-relative file to export, or all files
  * @property {boolean} help
@@ -104,6 +106,7 @@ function parseArgs(argv, cwd = process.cwd()) {
     repoPath: null,
     port: null,
     open: true,
+    staged: false,
     format: 'json',
     file: null,
     help: false,
@@ -138,6 +141,10 @@ function parseArgs(argv, cwd = process.cwd()) {
         options.open = false;
         break;
 
+      case '--staged':
+        options.staged = true;
+        break;
+
       case '-p':
       case '--port': {
         const value = rest[++i];
@@ -201,6 +208,10 @@ function parseArgs(argv, cwd = process.cwd()) {
     throw new UsageError('--file is only valid with reviewer export');
   }
 
+  if (options.staged && options.command !== 'serve') {
+    throw new UsageError('--staged is only valid when serving a review');
+  }
+
   return options;
 }
 
@@ -249,10 +260,11 @@ function parseFile(value, flag) {
  *
  * @param {string} origin e.g. http://127.0.0.1:4500
  * @param {string|null} repoPath
+ * @param {boolean} [staged]
  * @returns {string}
  */
-function buildUrl(origin, repoPath) {
-  if (!repoPath) return origin;
+function buildUrl(origin, repoPath, staged = false) {
+  if (!repoPath) return staged ? `${origin}/?staged=1` : origin;
 
   // Slashes are left as slashes. They are legal in a query value -- RFC 3986
   // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
@@ -263,7 +275,7 @@ function buildUrl(origin, repoPath) {
   //
   // Everything else stays encoded, including the characters that would
   // otherwise end the query and take the rest of the path with them.
-  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`;
+  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}${staged ? '&staged=1' : ''}`;
 }
 
 /**

package/lib/sessions.js

@@ -11,10 +11,11 @@ const crypto = require('crypto');
  */
 
 /**
- * @typedef {'working'|'lastCommit'|'range'} ReviewMode
+ * @typedef {'working'|'staged'|'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; `range`
  * diffs two refs the reviewer chose.
+ * `staged` diffs the index against HEAD without including working-tree edits.
  */
 
 /**

package/man/git-reviewer.1

@@ -51,6 +51,10 @@ Port to listen on. The default is 4500; if it is taken, a free one is used.
 .B \-\-no\-open
 Print the address instead of opening a browser.
 .TP
+.B \-\-staged
+Review only staged changes, comparing HEAD with the index. Unstaged edits are
+excluded, and an empty index comparison does not fall back to the last commit.
+.TP
 .BR \-f ", " \-\-format " \fIjson\fR|\fIprompt\fR"
 Export format. The default is json.
 .TP

package/package.json

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

@@ -2,6 +2,7 @@
 // In web mode, this will be http://localhost:4500
 // In Electron, this will be the random port Electron assigned
 const API_BASE = `${window.location.origin}/api`;
+const stagedByDefault = new URLSearchParams(window.location.search).get('staged') === '1';
 
 let currentRepoId = null;
 let currentFiles = [];
@@ -492,10 +493,10 @@ function renderScope(data) {
       document.getElementById('nextCommitBtn').disabled = true;
     }
   } else {
-    label.append('Uncommitted changes');
+    label.append(data.mode === 'staged' ? 'Staged changes' : 'Uncommitted changes');
     if (branch) label.append(' on ', strong(branch));
     meta.textContent = plural(data.files.length, 'file') + ' changed';
-    setNote(null);
+    setNote(data.mode === 'staged' ? 'The diff excludes unstaged changes. Saved comments are shared between views and may refer to other code; check their anchors.' : null);
   }
 
   row.classList.add('hidden');
@@ -781,7 +782,7 @@ async function loadRepo(scope = {}) {
       body: JSON.stringify(
         scope.commits ? { repoPath, commits: scope.commits }
           : scope.base ? { repoPath, base: scope.base, ...(scope.head ? { head: scope.head } : {}) }
-            : { repoPath }
+            : { repoPath, staged: stagedByDefault }
       )
     });
 
@@ -817,13 +818,13 @@ async function loadRepo(scope = {}) {
       // `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') {
+      if (data.mode === 'range' || data.mode === 'staged') {
         // 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'
+        showEmptyFileList(data.mode === 'staged' ? 'No staged changes.' : data.range?.kind !== 'commits'
           ? 'No files differ between these two.'
           : data.range.first === data.range.last
             ? 'This commit changes no files.'

package/server.js

@@ -12,7 +12,7 @@ const {
   resolveRepoFile,
   PathEscapeError
 } = require('./lib/paths');
-const { collectWorkingChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
+const { collectWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
 const { normalizeComments } = require('./lib/comments');
 const { formatReview, reviewFilename, commentsFilename } = require('./lib/review');
@@ -137,6 +137,18 @@ function createApp(options = {}) {
     const git = gitFactory(session.repoPath);
     const absolutePath = resolveRepoFile(session.repoPath, filePath);
 
+    if (session.mode === 'staged') {
+      try {
+        // `:0:` names the stage outright. A bare `:` reads a file called
+        // `0:foo` as stage 0 of `foo`, and shows the wrong file's text.
+        return await git.show([`:0:${filePath}`]);
+      } catch {
+        // A staged deletion has no index entry. Its old content comes from
+        // HEAD, even if a replacement now exists in the working tree.
+        return git.show([`HEAD:${filePath}`]).catch(() => { throw new FileNotFoundError(filePath); });
+      }
+    }
+
     if (session.range) {
       // A range is two commits, and the working tree is neither of them. It
       // used to be the fallback here, which was merely odd while the head of
@@ -222,6 +234,9 @@ function createApp(options = {}) {
   }
 
   async function diffForFile(git, session, filePath) {
+    if (session.mode === 'staged') {
+      return git.diff(['--cached', '--', filePath]);
+    }
     if (session.range) {
       return git.diff([session.range.from, session.range.head, '--', filePath]);
     }
@@ -768,7 +783,10 @@ 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, commits: run } = req.body ?? {};
+      const { base, head, commits: run, staged = false } = req.body ?? {};
+      if (typeof staged !== 'boolean' || (staged && (base != null || head != null || run != null))) {
+        return res.status(400).json({ error: 'Choose staged changes or a commit comparison, not both.' });
+      }
       const root = await repoRoot(repoPath, gitFactory);
       if (!root) {
         return res.status(400).json({ error: 'Not a valid git repository' });
@@ -781,7 +799,15 @@ function createApp(options = {}) {
       let range = null;
       let message;
 
-      if (run && typeof run === 'object') {
+      if (staged) {
+        try {
+          files = await collectStagedChanges(git);
+        } catch (error) {
+          return res.status(400).json({ error: error.message });
+        }
+        mode = 'staged';
+        message = files.length ? `Found ${files.length} staged file(s)` : 'No staged changes';
+      } else if (run && typeof run === 'object') {
         // Commits themselves, one or a run: see resolveCommitRun.
         try {
           range = await resolveCommitRun(git, `${run.from ?? ''}`.trim(), `${run.to ?? run.from ?? ''}`.trim());