git-reviewer 2.8.1 → 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-285-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              # 285 tests
+npm test              # 299 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -226,9 +226,25 @@ async function main() {
     stop();
   };
 
+  /**
+   * The last tab closed and did not come back.
+   *
+   * Only on a terminal. In the piped form, submitting is what hands the
+   * review over, and a closed tab is not a submitted review -- wiring this to
+   * the handoff would send a half-written review to something that starts
+   * editing files, which is a worse outcome by a wide margin than the Ctrl+C
+   * this saves.
+   */
+  const onIdle = handingOff
+    ? null
+    : () => {
+      note('\n  Browser closed. Stopping.\n');
+      stop();
+    };
+
   const server = await listen(
     options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
-    { onReviewSubmitted, handoff: handingOff }
+    { onReviewSubmitted, handoff: handingOff, onIdle }
   );
   const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
 
@@ -236,7 +252,7 @@ async function main() {
   if (repoPath) note(`  reviewing      ${repoPath}`);
   note(handingOff
     ? '\n  Submit the review in the browser and it will be written here.\n'
-    : '\n  Press Ctrl+C to stop.\n');
+    : '\n  Close the tab when you are done, or press Ctrl+C.\n');
 
   if (options.open && !(await openInBrowser(url))) {
     note('  Could not open a browser — open the URL above yourself.\n');

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.8.1",
+  "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/public/app.js

@@ -1718,7 +1718,31 @@ function getKeyboardShortcut(key, targetTagName, modifiers = {}) {
 }
 
 // Allow Enter key to load repo
+/**
+ * Tell the server this tab exists, by holding a connection open for as long
+ * as it does.
+ *
+ * There is nothing to read from this stream. The point is the socket: the
+ * browser closes it when the tab closes, which is the only notification of a
+ * closed tab that arrives whether you quit the browser, kill the window or
+ * lose the machine. `beforeunload` does not fire for all of those.
+ *
+ * EventSource reconnects on its own after a drop, which is what makes the
+ * server's grace period work -- a flaky connection comes back inside it and
+ * nothing is stopped.
+ */
+function watchFromThisTab() {
+  try {
+    new EventSource(`${API_BASE}/alive`);
+  } catch {
+    // Older browsers, or a page opened from a file:// URL. Losing this costs
+    // an automatic exit, not a review, so there is nothing to report.
+  }
+}
+
 document.addEventListener('DOMContentLoaded', () => {
+  watchFromThisTab();
+
   document.getElementById('repoPath').addEventListener('keypress', (e) => {
     if (e.key === 'Enter') {
       loadRepo();

package/server.js

@@ -55,6 +55,11 @@ class FileNotFoundError extends Error {
  * @param {boolean} [options.handoff] whether the caller is going to do
  *   something with a submitted review. Reported to the page so it can say
  *   where the review went instead of only offering a download.
+ * @param {() => void} [options.onIdle] called once the last browser tab has
+ *   been gone for `idleGraceMs`, so the process that started the server can
+ *   stop. Omitted means never: a server with no one to tell keeps serving.
+ * @param {number} [options.idleGraceMs] how long to wait after the last tab
+ *   leaves before deciding it is not coming back.
  * @returns {import('express').Express}
  */
 function createApp(options = {}) {
@@ -63,7 +68,9 @@ function createApp(options = {}) {
     sessions = new SessionStore(),
     git: gitFactory = simpleGit,
     onReviewSubmitted = null,
-    handoff = false
+    handoff = false,
+    onIdle = null,
+    idleGraceMs = 5000
   } = options;
 
   const app = express();
@@ -75,6 +82,11 @@ function createApp(options = {}) {
   app.locals.sessions = sessions;
   app.locals.reviewsDir = reviewsDir;
 
+  // How many tabs are currently holding `/api/alive` open, and the timer that
+  // starts when that reaches zero. See the route for why it is a timer.
+  let watching = 0;
+  let idleTimer = null;
+
   /**
    * Look up the session for a request, or answer 400.
    *
@@ -222,6 +234,59 @@ function createApp(options = {}) {
     next();
   }
 
+  /**
+   * Held open for as long as a tab is watching, so the server can tell when
+   * the last one has gone.
+   *
+   * The connection *is* the signal. An open page holds this response open and
+   * closing the page closes it, so there is no heartbeat interval to tune, and
+   * two tabs are two connections rather than one flag that either close
+   * clears. `sameOriginOnly` is here for the same reason it is on the two
+   * below: without it a page on another site could hold this open and keep a
+   * server alive that its owner had finished with.
+   *
+   * Nothing happens at the moment a watcher leaves. A reload closes and
+   * reopens within milliseconds, and a dropped connection reopens when
+   * EventSource retries -- at the instant it happens neither is
+   * distinguishable from someone closing the tab for good. So the last one
+   * leaving starts a timer and the next to arrive cancels it. Guessing wrong
+   * ends a review somebody is in the middle of, which is worth five seconds.
+   *
+   * A server nobody ever opened is not idle. `watching` only falls to zero
+   * after having been above it, so `reviewer` whose browser never launched
+   * keeps serving rather than exiting into an empty terminal.
+   */
+  app.get('/api/alive', sameOriginOnly, (req, res) => {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    watching += 1;
+
+    res.set({
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive'
+    });
+    // A comment frame, which EventSource ignores. Sending it now is what
+    // flushes the headers, so the client is connected rather than pending.
+    res.write(': watching\n\n');
+
+    res.on('close', () => {
+      watching -= 1;
+      if (watching > 0 || !onIdle) return;
+
+      idleTimer = setTimeout(() => {
+        idleTimer = null;
+        if (watching === 0) onIdle();
+      }, idleGraceMs);
+      // The listening socket is what holds the process open; this timer
+      // should not be able to on its own, or a closed server would sit
+      // waiting out the grace period before the process could exit.
+      idleTimer.unref();
+    });
+  });
+
   /** List the directories inside one, so a repository can be found by looking. */
   app.get('/api/browse', sameOriginOnly, async (req, res) => {
     try {
@@ -398,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
       };