git-reviewer 2.15.0 → 2.17.0

package/lib/threads.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * A review comment as a conversation: the reviewer's comment, then follow-ups
+ * from either side. An agent connected to a review answers in these threads,
+ * so this is where "what is still waiting for an answer" and "what is new
+ * since I last looked" are decided -- once, for the page, the channel and the
+ * background session alike.
+ */
+
+/**
+ * Who wrote the last word in a thread: null for the reviewer, otherwise the
+ * `by` of the last follow-up.
+ *
+ * @param {import('./comments').Comment} comment
+ * @returns {string|null}
+ */
+function lastAuthor(comment) {
+  const followUps = comment.followUps ?? [];
+  return followUps.length === 0 ? null : (followUps[followUps.length - 1].by ?? null);
+}
+
+/**
+ * Threads whose last word is the reviewer's: what an agent has yet to answer.
+ *
+ * @template {import('./comments').Comment} T
+ * @param {T[]} comments
+ * @returns {T[]}
+ */
+function awaitingAnswer(comments) {
+  return comments.filter(comment => lastAuthor(comment) === null);
+}
+
+/** The identity a follow-up is merged by: its key, or what it said and when. */
+function followUpIdentity(followUp) {
+  return followUp.key ?? JSON.stringify([followUp.timestamp ?? null, followUp.text, followUp.by ?? null]);
+}
+
+/**
+ * Every follow-up in either list, once.
+ *
+ * Follow-ups are only ever added -- nothing in the page or the API removes
+ * one -- so a follow-up present on either side is one somebody wrote, and
+ * the union is the only merge that cannot lose an answer. `ours` keeps its
+ * order; follow-ups only `theirs` holds are placed by timestamp.
+ *
+ * @param {import('./comments').FollowUp[]} [ours]
+ * @param {import('./comments').FollowUp[]} [theirs]
+ * @returns {import('./comments').FollowUp[]}
+ */
+function unionFollowUps(ours = [], theirs = []) {
+  const merged = [...ours];
+  const seen = new Set(ours.map(followUpIdentity));
+
+  for (const followUp of theirs) {
+    const identity = followUpIdentity(followUp);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+
+    // After the last entry that is not later than it, so an answer that was
+    // written while this side was adding its own lands where it happened.
+    const at = followUp.timestamp ?? '';
+    let index = merged.length;
+    if (at) {
+      while (index > 0 && (merged[index - 1].timestamp ?? '') > at) index--;
+    }
+    merged.splice(index, 0, followUp);
+  }
+
+  return merged;
+}
+
+/**
+ * Carry over follow-ups a save never saw.
+ *
+ * A tab saves the whole list it holds. An agent may have answered in a thread
+ * after that tab last heard from the server; saving the tab's copy of the
+ * thread as it stands would erase the answer. For every comment present both
+ * in the save and on disk, the follow-ups on disk are kept alongside the
+ * tab's.
+ *
+ * @param {import('./comments').Comment[]} incoming keyed comments being saved
+ * @param {import('./comments').Comment[]} current keyed comments on disk
+ * @returns {import('./comments').Comment[]}
+ */
+function keepFollowUpsFrom(incoming, current) {
+  const onDisk = new Map(current.map(comment => [comment.key, comment]));
+
+  return incoming.map(comment => {
+    const stored = onDisk.get(comment.key);
+    if (!stored?.followUps?.length) return comment;
+
+    const followUps = unionFollowUps(comment.followUps, stored.followUps);
+    return followUps.length === (comment.followUps?.length ?? 0) ? comment : { ...comment, followUps };
+  });
+}
+
+/**
+ * What the reviewer has said in `next` that was not in `prev`: new comments,
+ * and new follow-ups the reviewer wrote. Each comes back once, keyed, so an
+ * agent can be told about it exactly once.
+ *
+ * @param {import('./comments').Comment[]} prev keyed
+ * @param {import('./comments').Comment[]} next keyed
+ * @returns {Array<{comment: import('./comments').Comment, followUp: import('./comments').FollowUp|null}>}
+ */
+function newReviewerMessages(prev, next) {
+  const before = new Map(prev.map(comment => [comment.key, comment]));
+  const messages = [];
+
+  for (const comment of next) {
+    const old = before.get(comment.key);
+    if (!old) {
+      messages.push({ comment, followUp: null });
+    }
+    const known = new Set((old?.followUps ?? []).map(followUpIdentity));
+    for (const followUp of comment.followUps ?? []) {
+      if (followUp.by || known.has(followUpIdentity(followUp))) continue;
+      // A brand-new comment arriving with follow-ups already on it is one
+      // message, not several: the agent is told about the thread once.
+      if (!old) continue;
+      messages.push({ comment, followUp });
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * The thread an agent is being asked to answer, as plain text.
+ *
+ * Shared by every way an agent can be connected, so a background session and
+ * a live one are asked the same question in the same words.
+ *
+ * @param {import('./comments').Comment} comment
+ * @returns {string}
+ */
+function describeThread(comment) {
+  const lines = [`${comment.file}, line ${comment.line}`];
+  if (comment.lineContent !== undefined && comment.lineContent !== null && comment.lineContent !== '') {
+    lines.push(`Line: ${comment.lineContent.trim()}`);
+  }
+  if (comment.selectedText) {
+    lines.push(`Selected: ${comment.selectedText.trim()}`);
+  }
+  lines.push('', `Reviewer: ${comment.text}`);
+  for (const followUp of comment.followUps ?? []) {
+    lines.push(`${followUp.by ? `${followUp.by} (you)` : 'Reviewer'}: ${followUp.text}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Append an agent's answer to a thread.
+ *
+ * @param {import('./comments').Comment[]} comments keyed
+ * @param {string} key comment to answer
+ * @param {import('./comments').FollowUp} reply
+ * @returns {import('./comments').Comment[]|null} the new list, or null when no comment has that key
+ */
+function appendReply(comments, key, reply) {
+  let found = false;
+  const updated = comments.map(comment => {
+    if (comment.key !== key) return comment;
+    found = true;
+    return { ...comment, followUps: [...(comment.followUps ?? []), reply] };
+  });
+  return found ? updated : null;
+}
+
+module.exports = {
+  lastAuthor,
+  awaitingAnswer,
+  unionFollowUps,
+  keepFollowUpsFrom,
+  newReviewerMessages,
+  describeThread,
+  appendReply,
+  followUpIdentity
+};

package/lib/watch.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { readSavedComments } = require('./store');
+const { commentsFilename } = require('./review');
+
+/**
+ * Hearing about a review changing, whoever changed it.
+ *
+ * The comments file is the source of truth and, now that agents answer in
+ * threads, it has writers other than the page: `reviewer channel` running
+ * inside a Claude Code session, `reviewer reply`, a background session the
+ * server started. Each of them writes the file; everyone interested watches
+ * it. That keeps the writers from needing to know who is listening, or where.
+ *
+ * `fs.watch` gives the change within milliseconds where the platform supports
+ * it. A slow poll runs alongside, because there are filesystems where
+ * `fs.watch` is silently deaf -- network mounts, some containers -- and a
+ * reply that never shows up is worse than one that shows up a second late.
+ */
+
+const DEBOUNCE_MS = 25;
+const POLL_MS = 1500;
+
+/**
+ * Watch one repository's saved comments.
+ *
+ * `onChange` is called with what was read whenever `lastUpdated` moves, and
+ * once at the start with the state as it stands, so a caller never has to
+ * read separately and race the first change.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @param {(state: import('./store').SavedReview) => void} onChange
+ * @param {object} [options]
+ * @param {number} [options.pollMs]
+ * @param {(error: Error) => void} [options.onError] a file that cannot be read or parsed; the watch carries on
+ * @returns {{close: () => void, ready: Promise<void>}}
+ */
+function watchComments(reviewsDir, repoPath, onChange, { pollMs = POLL_MS, onError = () => {} } = {}) {
+  const filename = commentsFilename(repoPath);
+  const file = path.join(reviewsDir, filename);
+
+  let closed = false;
+  let lastSeen;
+  let lastStat = null;
+  let timer = null;
+  let reading = null;
+  let again = false;
+
+  const check = async () => {
+    if (closed) return;
+    if (reading) {
+      again = true;
+      return reading;
+    }
+    reading = (async () => {
+      try {
+        const state = await readSavedComments(reviewsDir, repoPath);
+        if (closed) return;
+        if (state.lastUpdated !== lastSeen) {
+          lastSeen = state.lastUpdated;
+          onChange(state);
+        }
+      } catch (error) {
+        // A file caught mid-replace by a writer that is not atomic, or one
+        // hand-edited into invalid JSON. Say so and keep watching: the next
+        // write will be readable.
+        if (!closed) onError(error);
+      }
+    })();
+    try {
+      await reading;
+    } finally {
+      reading = null;
+      if (again && !closed) {
+        again = false;
+        check();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (closed) return;
+    clearTimeout(timer);
+    timer = setTimeout(check, DEBOUNCE_MS);
+  };
+
+  let watcher = null;
+  try {
+    fs.mkdirSync(reviewsDir, { recursive: true });
+    // The directory, not the file: an atomic write replaces the file, and a
+    // watch on the old one would go quiet after the first save.
+    watcher = fs.watch(reviewsDir, (event, name) => {
+      if (!name || name === filename) schedule();
+    });
+    watcher.on('error', () => {
+      watcher?.close();
+      watcher = null;
+    });
+  } catch {
+    watcher = null; // the poll below still covers it
+  }
+
+  const poll = setInterval(() => {
+    fs.stat(file, (error, stat) => {
+      const signature = error ? null : `${stat.mtimeMs}:${stat.size}`;
+      if (signature !== lastStat) {
+        lastStat = signature;
+        check();
+      }
+    });
+  }, pollMs);
+  poll.unref();
+
+  const ready = check();
+
+  return {
+    ready,
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      clearInterval(poll);
+      watcher?.close();
+    }
+  };
+}
+
+module.exports = { watchComments };

package/man/git-reviewer.1

@@ -17,6 +17,23 @@ git-reviewer, reviewer \- review local git changes in your browser, and hand the
 .IR json | prompt ]
 .RB [ \-\-file
 .IR path ]
+.br
+.B git reviewer connect
+.RI [ repository ]
+.RB [ \-\-session
+.IR id ]
+.RB [ \-\-fork ]
+.RB [ \-\-list ]
+.br
+.B git reviewer reply
+.I key text
+.RB [ \-\-repo
+.IR path ]
+.RB [ \-\-as
+.IR name ]
+.br
+.B git reviewer watch
+.RI [ repository ]
 .SH DESCRIPTION
 Opens the uncommitted changes of a git repository, or its last commit on a
 clean tree, as a pull-request style review in your browser: inline comments
@@ -44,6 +61,36 @@ is the same program under a shorter name.
 .B export
 Print the saved review of a repository to stdout, as JSON or as a prompt for
 a coding agent.
+.TP
+.B connect
+Resume the Claude Code session that worked in the repository, with reviewer
+attached as a channel: every comment written in the review is sent to the
+session as it is written, and the session answers in the thread.
+.B \-\-list
+shows the sessions;
+.B \-\-session
+picks one by id or id prefix;
+.B \-\-fork
+resumes a copy. Claude Code asks once, at startup, to confirm the channel.
+.TP
+.B reply
+Post a reply in a comment thread, as an agent. Inside Claude Code it is
+signed
+.BR claude ,
+elsewhere
+.B agent
+unless
+.B \-\-as
+names who it is from. Exits 1 if no comment has that key.
+.TP
+.B watch
+Print each comment waiting for an answer, then each new comment or reply
+from the reviewer, as one JSON line, until interrupted.
+.TP
+.B channel
+The MCP server
+.B connect
+asks Claude Code to run, speaking JSON-RPC over stdio. Not run by hand.
 .SH OPTIONS
 .TP
 .BR \-p ", " \-\-port " \fIn\fR"

package/package.json

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