git-reviewer 2.9.0 → 2.9.1

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-291-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-299-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              # 291 tests
+npm test              # 299 tests
 npm run test:watch
 npm run test:coverage
 ```

package/lib/agent.js

@@ -176,6 +176,40 @@ function toAgentComment(comment, id) {
   return entry;
 }
 
+/**
+ * What this review was of, in one line.
+ *
+ * An agent applying a review needs to know whether it is looking at
+ * uncommitted work or at a commit that is already in history -- "make this
+ * change" means a different thing in each. Both used to print
+ * `Reviewed at commit: <sha>`, which in `working` mode is not merely vague:
+ * the review is of changes that are *not* in that commit, and saying they
+ * are is the kind of authoritative-looking line this project exists to
+ * avoid.
+ *
+ * A null mode is a review exported from a file written before the mode was
+ * recorded. Reporting only where HEAD is, exactly as it always did, is the
+ * honest answer there -- nothing on disk says what was compared.
+ *
+ * @param {ReviewDocument} document
+ * @returns {string|null}
+ */
+function describeScope({ repository, mode }) {
+  const at = repository.head ? ` (${repository.head})` : '';
+
+  if (mode === 'working') {
+    return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
+  }
+
+  if (mode === 'lastCommit') {
+    return repository.head
+      ? `Reviewed: commit ${repository.head}, against its parent.`
+      : 'Reviewed: the most recent commit, against its parent.';
+  }
+
+  return repository.head ? `Reviewed at commit: ${repository.head}` : null;
+}
+
 /**
  * Render a review as instructions for a coding agent.
  *
@@ -192,7 +226,7 @@ function formatPrompt(document) {
     '# Code review to address',
     '',
     `Repository: ${repository.path}`,
-    repository.head ? `Reviewed at commit: ${repository.head}` : null,
+    describeScope(document),
     `${summary.comments} comment(s) across ${summary.files} file(s), written ${document.generatedAt}.`,
     '',
     'Work through every comment below and make the change it asks for, or, if',

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 } = await readSavedComments(reviewsDir, repoPath);
+  const { comments, mode } = 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 }),
+    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode }),
     { file }
   );
 

package/lib/store.js

@@ -74,7 +74,10 @@ async function readJson(file) {
  *
  * @param {string} reviewsDir
  * @param {string} repoPath
- * @returns {Promise<{comments: object[], adopted: boolean}>}
+ * @returns {Promise<{comments: object[], mode: string|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.
  * @throws {ReviewOwnershipError} when the current file names another repository
  */
 async function readSavedComments(reviewsDir, repoPath) {
@@ -87,15 +90,15 @@ async function readSavedComments(reviewsDir, repoPath) {
     if (!belongsTo(saved.repoPath, repoPath)) {
       throw new ReviewOwnershipError(repoPath, saved.repoPath);
     }
-    return { comments: saved.comments ?? [], adopted: false };
+    return { comments: saved.comments ?? [], mode: saved.mode ?? null, adopted: false };
   }
 
   const legacyName = legacyCommentsFilename(repoPath);
-  if (legacyName === commentsFilename(repoPath)) return { comments: [], adopted: false };
+  if (legacyName === commentsFilename(repoPath)) return { comments: [], mode: null, adopted: false };
 
   const legacy = await readJson(path.join(reviewsDir, legacyName));
   if (legacy === null || !belongsTo(legacy.repoPath, repoPath)) {
-    return { comments: [], adopted: false };
+    return { comments: [], mode: null, adopted: false };
   }
 
   // Move it under the new name so the next read is a plain hit and the old
@@ -107,7 +110,7 @@ async function readSavedComments(reviewsDir, repoPath) {
     /* the comments are already in hand; renaming is housekeeping */
   }
 
-  return { comments: legacy.comments ?? [], adopted: true };
+  return { comments: legacy.comments ?? [], mode: legacy.mode ?? null, adopted: true };
 }
 
 module.exports = { readSavedComments, ReviewOwnershipError, belongsTo };

package/package.json

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

@@ -463,9 +463,15 @@ function createApp(options = {}) {
 
       await fs.mkdir(reviewsDir, { recursive: true });
 
+      // `mode` is on the envelope rather than on each comment: it describes
+      // the review, not any one remark in it, and it is what lets `reviewer
+      // export` say what was compared. Without it an exported review could
+      // only report where HEAD is, which says nothing about whether the
+      // comments are about committed work or uncommitted work.
       const data = {
         repoPath: session.repoPath,
         lastUpdated: new Date().toISOString(),
+        mode: session.mode,
         comments: normalized
       };