git-reviewer 2.14.1 → 2.16.0

package/server.js

@@ -12,16 +12,24 @@ const {
   resolveRepoFile,
   PathEscapeError
 } = require('./lib/paths');
-const { collectWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
+const { collectWorkingTreeChanges, describeWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
-const { normalizeComments } = require('./lib/comments');
+const { normalizeComments, withKeys } = require('./lib/comments');
+const { keepFollowUpsFrom } = require('./lib/threads');
 const { formatReview, reviewFilename, commentsFilename } = require('./lib/review');
-const { buildReviewDocument } = require('./lib/agent');
-const { readSavedComments, ReviewOwnershipError } = require('./lib/store');
+const { buildReviewDocument, describeScope } = require('./lib/agent');
+const { readSavedComments, updateSavedComments, ReviewOwnershipError } = require('./lib/store');
 const { repoRoot } = require('./lib/repo');
 const { browse } = require('./lib/browse');
 const { recordRecent, describeRecents } = require('./lib/recents');
 const { listReviews } = require('./lib/export');
+const { EventEmitter } = require('events');
+const { watchComments } = require('./lib/watch');
+const { watchAgents } = require('./lib/presence');
+const { listClaudeSessions, findClaudeSession } = require('./lib/claude-sessions');
+const { BackgroundSession } = require('./lib/claude-background');
+const { Answerer } = require('./lib/answerer');
+const { resolveClaudeCommand } = require('./lib/claude-command');
 
 const DEFAULT_PORT = 4500;
 const DEFAULT_HOST = '127.0.0.1';
@@ -60,6 +68,15 @@ function loopbackHostOnly(req, res, next) {
 }
 
 
+/**
+ * An agent's presence record, as the page is told about it.
+ *
+ * @param {import('./lib/presence').AgentPresence} agent
+ */
+function describeAgent({ id, kind, agent, session, title, startedAt, working }) {
+  return { id, kind, agent, session, title, startedAt, working };
+}
+
 /** A path inside the repository that names nothing, on disk or at HEAD. */
 class FileNotFoundError extends Error {
   /** @param {string} filePath */
@@ -95,6 +112,10 @@ class FileNotFoundError extends Error {
  *   leaves before deciding it is not coming back.
  * @param {boolean} [options.loopbackOnly] refuse any request whose `Host` is
  *   not a loopback name. `startServer` turns it on when it binds to loopback.
+ * @param {object} [options.claude] how Claude Code is found and run, for
+ *   answering comments from a session: `command` (default `claude`, or
+ *   `REVIEWER_CLAUDE`), `configDir` (where its sessions are kept) and
+ *   `spawn`, all injectable for tests.
  * @returns {import('express').Express}
  */
 // How far back the range picker offers to go. Long enough to cover the work
@@ -122,8 +143,10 @@ function createApp(options = {}) {
     handoff = false,
     onIdle = null,
     idleGraceMs = 5000,
-    loopbackOnly = false
+    loopbackOnly = false,
+    claude = {}
   } = options;
+  const claudeCommand = claude.command ?? process.env.REVIEWER_CLAUDE ?? 'claude';
 
   const app = express();
 
@@ -136,6 +159,38 @@ function createApp(options = {}) {
   app.locals.sessions = sessions;
   app.locals.reviewsDir = reviewsDir;
 
+  // Background Claude Code sessions answering comments, one per repository
+  // at most, and the feed their answers-in-progress go out on. An answer is
+  // only written to the review once it is finished; until then the words
+  // arriving are sent to the page directly, not written to disk word by word.
+  /** @type {Map<string, Answerer>} */
+  const answerers = new Map();
+  const live = new EventEmitter();
+  live.setMaxListeners(0);
+
+  // Connecting and disconnecting a repository's background session happen
+  // one at a time. Two connects racing would each stop the session they
+  // found -- none -- and both start one, and the first would be left
+  // running with nothing to stop it.
+  /** @type {Map<string, Promise<void>>} */
+  const agentLocks = new Map();
+  const withAgentLock = (repoPath, task) => {
+    const previous = agentLocks.get(repoPath) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    const tail = run.then(() => {}, () => {});
+    agentLocks.set(repoPath, tail);
+    tail.then(() => {
+      if (agentLocks.get(repoPath) === tail) agentLocks.delete(repoPath);
+    });
+    return run;
+  };
+
+  app.locals.stopAgents = async () => {
+    const running = [...answerers.values()];
+    answerers.clear();
+    await Promise.all(running.map(answerer => answerer.stop()));
+  };
+
   // 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;
@@ -756,22 +811,23 @@ function createApp(options = {}) {
    * after having been above it, so `reviewer` whose browser never launched
    * keeps serving rather than exiting into an empty terminal.
    */
-  app.get('/api/alive', (req, res) => {
+  /**
+   * Count a tab as watching for as long as `res` stays open.
+   *
+   * Shared by `/api/alive` and `/api/events`: a tab holds exactly one of
+   * them, the first before a repository is open and the second after.
+   * Browsers allow six connections to one host, and a tab holding two would
+   * leave three tabs nothing to save with.
+   *
+   * @param {import('express').Response} res
+   */
+  function countWatcher(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;
@@ -785,6 +841,19 @@ function createApp(options = {}) {
       // waiting out the grace period before the process could exit.
       idleTimer.unref();
     });
+  }
+
+  app.get('/api/alive', (req, res) => {
+    countWatcher(res);
+
+    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');
   });
 
   /** List the directories inside one, so a repository can be found by looking. */
@@ -838,7 +907,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, staged = false } = req.body ?? {};
+      const { base, head, commits: run, staged = false, untracked = true } = req.body ?? {};
+      if (typeof untracked !== 'boolean') {
+        return res.status(400).json({ error: 'The untracked option must be a boolean.' });
+      }
       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.' });
       }
@@ -887,12 +959,14 @@ function createApp(options = {}) {
         mode = 'range';
         message = describeRange(range, files.length);
       } else {
-        files = collectWorkingChanges(await git.status());
+        files = await collectWorkingTreeChanges(git, untracked);
         mode = 'working';
-        message = `Found ${files.length} changed file(s)`;
+        message = describeWorkingChanges(files, untracked);
 
         // A clean tree has nothing to review, so fall back to the last commit.
-        if (files.length === 0) {
+        // Hiding untracked files is an explicit working-tree scope. An empty
+        // tracked review must not silently become a review of committed work.
+        if (files.length === 0 && untracked) {
           try {
             const lastCommit = await resolveRange(git, 'HEAD~1', 'HEAD');
             const commitFiles = await collectRangeChanges(git, lastCommit);
@@ -910,7 +984,10 @@ function createApp(options = {}) {
         }
       }
 
-      const repoId = sessions.create(root, mode, range);
+      const repoId = sessions.create(root, mode, range, untracked);
+      sessions.get(repoId).foldedDirectories = new Map(
+        files.filter(file => file.directory).map(file => [file.path, file.fileCount])
+      );
       // stderr, not stdout. `reviewer | claude -p ...` puts the finished
       // review on stdout, and anything else written there lands in the middle
       // of it. Progress is for the person watching; stdout is for the pipe.
@@ -925,7 +1002,7 @@ function createApp(options = {}) {
 
       // `repoPath` in the response is the resolved root, not what was asked
       // for, so the page can show which repository it actually opened.
-      res.json({ repoId, files, repoPath: root, mode, range, message });
+      res.json({ repoId, files, repoPath: root, mode, range, message, untracked });
     } catch (error) {
       console.error('Load repo error:', error);
       res.status(500).json({ error: error.message });
@@ -946,6 +1023,10 @@ function createApp(options = {}) {
       // works because of statement order is not a containment check.
       resolveRepoFile(session.repoPath, filePath);
 
+      if (session.foldedDirectories?.has(filePath)) {
+        return res.json({ filePath, directory: true, fileCount: session.foldedDirectories.get(filePath), binary: false, diffLines: [] });
+      }
+
       const git = gitFactory(session.repoPath);
       const diffText = await diffForFile(git, session, filePath);
 
@@ -978,6 +1059,11 @@ function createApp(options = {}) {
       const session = requireSession(res, repoId);
       if (!session) return;
 
+      resolveRepoFile(session.repoPath, filePath);
+      if (session.foldedDirectories?.has(filePath)) {
+        return res.json({ filePath, directory: true, fileCount: session.foldedDirectories.get(filePath), lines: [] });
+      }
+
       const content = await readFileForMode(session, filePath);
       res.json({ filePath, lines: content.split('\n') });
     } catch (error) {
@@ -992,13 +1078,30 @@ function createApp(options = {}) {
     }
   });
 
-  /** Persist the current comments. Called on every edit. */
+  /**
+   * Persist the current comments. Called on every edit.
+   *
+   * A caller that sends the `lastUpdated` it loaded saves conditionally
+   * (#107): if the file has moved on since -- another tab, `reviewer
+   * resolve`, an agent -- the save is refused with 409 and the current
+   * comments and stamp ride along, so the caller can merge and retry
+   * instead of silently overwriting what it never saw. A caller that
+   * sends no `lastUpdated` at all keeps the old unconditional behaviour:
+   * scripts written against the original route are not tabs racing each
+   * other, and breaking them would not protect anyone.
+   */
   app.post('/api/save-comments', async (req, res) => {
     try {
       const { repoId, comments } = req.body ?? {};
       const session = requireSession(res, repoId);
       if (!session) return;
 
+      const conditional = Object.prototype.hasOwnProperty.call(req.body ?? {}, 'lastUpdated');
+      const expected = req.body?.lastUpdated ?? null;
+      if (conditional && expected !== null && typeof expected !== 'string') {
+        return res.status(400).json({ error: 'lastUpdated must be a string or null' });
+      }
+
       let normalized;
       try {
         normalized = normalizeComments(comments);
@@ -1006,26 +1109,47 @@ function createApp(options = {}) {
         return res.status(400).json({ error: error.message });
       }
 
-      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,
-        range: session.range,
-        comments: normalized
-      };
+      // Comments posted without keys -- older pages, scripts -- get the key
+      // their content derives, so re-posting the same list keeps each
+      // comment's identity, and the follow-ups below can find their thread.
+      const incoming = withKeys(normalized);
+
+      let refusal = null;
+      const saved = await updateSavedComments(reviewsDir, session.repoPath, current => {
+        if (conditional && (current.lastUpdated ?? null) !== expected) {
+          refusal = {
+            error: 'Comments have changed since they were loaded. Reload, merge and retry.',
+            comments: current.comments,
+            lastUpdated: current.lastUpdated ?? null
+          };
+          return null;
+        }
 
-      const target = path.join(reviewsDir, commentsFilename(session.repoPath));
-      await fs.writeFile(target, `${JSON.stringify(data, null, 2)}\n`);
+        // `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.
+        //
+        // Follow-ups already on disk are kept for every comment the save
+        // still holds: an agent may have answered in a thread since this tab
+        // last heard from the server, and a whole-list save must not erase it.
+        return {
+          comments: keepFollowUpsFrom(incoming, current.comments),
+          scope: { mode: session.mode, range: session.range, untracked: session.untracked }
+        };
+      });
 
-      res.json({ message: 'Comments saved successfully' });
+      const outcome = refusal
+        ? { status: 409, body: refusal }
+        // What was written, which can be more than what was sent -- the
+        // follow-ups kept from disk -- so the page can show it at once.
+        : { status: 200, body: { message: 'Comments saved successfully', lastUpdated: saved.lastUpdated, comments: saved.comments } };
+      res.status(outcome.status).json(outcome.body);
     } catch (error) {
+      if (error instanceof ReviewOwnershipError) {
+        return res.status(409).json({ error: error.message });
+      }
       console.error('Save comments error:', error);
       res.status(500).json({ error: error.message });
     }
@@ -1037,8 +1161,8 @@ function createApp(options = {}) {
       const session = requireSession(res, req.params.repoId);
       if (!session) return;
 
-      const { comments } = await readSavedComments(reviewsDir, session.repoPath);
-      res.json({ comments });
+      const { comments, lastUpdated } = await readSavedComments(reviewsDir, session.repoPath);
+      res.json({ comments, lastUpdated: lastUpdated ?? null });
     } catch (error) {
       if (error instanceof ReviewOwnershipError) {
         return res.status(409).json({ error: error.message });
@@ -1066,7 +1190,6 @@ function createApp(options = {}) {
       }
 
       const generatedAt = new Date();
-      const reviewContent = formatReview({ repoPath: session.repoPath, comments, generatedAt });
       const filename = reviewFilename(session.repoPath, generatedAt);
 
       // The commit is worth recording for anything acting on the review later:
@@ -1082,7 +1205,12 @@ function createApp(options = {}) {
         head,
         branch,
         mode: session.mode,
-        range: session.range
+        range: session.range,
+        untracked: session.untracked
+      });
+      const reviewContent = formatReview({
+        repoPath: session.repoPath, comments, generatedAt,
+        scope: document.untracked === false ? describeScope(document) : null
       });
       const documentFilename = filename.replace(/\.txt$/, '.json');
 
@@ -1137,6 +1265,170 @@ function createApp(options = {}) {
     }
   });
 
+  /**
+   * The live feed for one open review.
+   *
+   * `comments` whenever the saved comments change -- whoever changed them:
+   * another tab, an agent answering in a thread, `reviewer reply` -- and once
+   * on connecting; `agents` whenever an agent connects, leaves, or starts on
+   * a thread; and, while a background session here is answering, `partial`
+   * with the answer as far as it has got. The page applies `comments` the way
+   * it applies a refused save, so nothing it is holding is lost.
+   */
+  app.get('/api/events/:repoId', (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+
+    // The page's one long-lived connection once a repository is open, so it
+    // is also how the server knows the tab is still there (see /api/alive).
+    countWatcher(res);
+
+    res.set({
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive'
+    });
+    res.write(': events\n\n');
+
+    const send = (event, data) => {
+      if (!res.writableEnded) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+
+    const comments = watchComments(reviewsDir, session.repoPath, state => {
+      send('comments', { comments: state.comments, lastUpdated: state.lastUpdated ?? null });
+    }, { onError: error => console.error('Review events:', error.message) });
+    const agents = watchAgents(reviewsDir, session.repoPath, list => {
+      send('agents', { agents: list.map(describeAgent) });
+    });
+    const onLive = (repoPath, event, data) => {
+      if (repoPath === session.repoPath) send(event, data);
+    };
+    live.on('event', onLive);
+    send('answerer', answerers.get(session.repoPath)?.status() ?? null);
+
+    // Proxies close a connection that has been quiet for a minute or two.
+    const keepAlive = setInterval(() => res.write(': ping\n\n'), 20000);
+    keepAlive.unref();
+
+    res.on('close', () => {
+      comments.close();
+      agents.close();
+      live.off('event', onLive);
+      clearInterval(keepAlive);
+    });
+  });
+
+  /**
+   * The Claude Code sessions that worked in this repository, newest first,
+   * to choose the one that should answer -- normally the one that wrote the
+   * code under review.
+   */
+  app.get('/api/agent/sessions/:repoId', async (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+    try {
+      const sessions = await listClaudeSessions(session.repoPath, { configDir: claude.configDir });
+      res.json({ sessions, answerer: answerers.get(session.repoPath)?.status() ?? null });
+    } catch (error) {
+      console.error('Session list error:', error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  /**
+   * Have a Claude Code session answer this review's comments.
+   *
+   * Resumes the session in the background -- as a copy unless `fork` is
+   * false -- and puts every thread waiting for an answer to it, then every
+   * comment and reply the reviewer writes from now on. Only a session that
+   * worked in this repository can be named: the id goes on a command line,
+   * and the list is the whitelist.
+   */
+  app.post('/api/agent/connect', async (req, res) => {
+    try {
+      const { repoId, sessionId, fork = true } = req.body ?? {};
+      const session = requireSession(res, repoId);
+      if (!session) return;
+      if (typeof fork !== 'boolean') {
+        return res.status(400).json({ error: 'fork must be true or false' });
+      }
+
+      const found = await findClaudeSession(session.repoPath, sessionId, { configDir: claude.configDir });
+      if (!found) {
+        return res.status(404).json({ error: 'No Claude Code session with that id has worked in this repository.' });
+      }
+
+      const answerer = await withAgentLock(session.repoPath, async () => {
+        await answerers.get(session.repoPath)?.stop();
+        answerers.delete(session.repoPath);
+        return startAnswerer(session, found, fork);
+      });
+
+      console.error(`Answering comments from Claude Code session ${found.id}${fork ? ' (in a copy)' : ''}`);
+      live.emit('event', session.repoPath, 'answerer', answerer.status());
+      res.json({ answerer: answerer.status() });
+    } catch (error) {
+      console.error('Agent connect error:', error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  /**
+   * Start a background session answering a repository's comments.
+   *
+   * @param {{repoPath: string}} session
+   * @param {import('./lib/claude-sessions').ClaudeSession} found
+   * @param {boolean} fork
+   * @returns {Promise<Answerer>}
+   */
+  async function startAnswerer(session, found, fork) {
+    const about = found.title ?? found.firstPrompt ?? found.id;
+    // Claude Code finds a session by the directory it ran in. If that has
+    // since been removed, the repository root is the next best place to
+    // run from, rather than a spawn error that reads like a missing binary.
+    const cwd = await fs.access(found.cwd).then(() => found.cwd, () => session.repoPath);
+    const background = new BackgroundSession({
+      sessionId: found.id,
+      cwd,
+      fork,
+      name: fork ? `Review answers: ${about}`.slice(0, 80) : null,
+      claude: claude.spawn ? claudeCommand : resolveClaudeCommand(claudeCommand),
+      spawn: claude.spawn
+    });
+    const answerer = new Answerer({
+      reviewsDir,
+      repoPath: session.repoPath,
+      session: background,
+      claudeSession: { id: found.id, title: about }
+    });
+    answerer.on('partial', data => live.emit('event', session.repoPath, 'partial', data));
+    answerer.on('failed', data => live.emit('event', session.repoPath, 'agent-error', data));
+    answerer.on('status', status => live.emit('event', session.repoPath, 'answerer', status));
+    answerer.on('stopped', () => {
+      if (answerers.get(session.repoPath) === answerer) answerers.delete(session.repoPath);
+      live.emit('event', session.repoPath, 'answerer', null);
+    });
+    answerers.set(session.repoPath, answerer);
+    background.start();
+    return answerer;
+  }
+
+  /** Stop the background session answering this review, if there is one. */
+  app.post('/api/agent/disconnect', async (req, res) => {
+    const { repoId } = req.body ?? {};
+    const session = requireSession(res, repoId);
+    if (!session) return;
+
+    const answerer = await withAgentLock(session.repoPath, async () => {
+      const running = answerers.get(session.repoPath);
+      answerers.delete(session.repoPath);
+      await running?.stop();
+      return running;
+    });
+    live.emit('event', session.repoPath, 'answerer', null);
+    res.json({ disconnected: Boolean(answerer) });
+  });
+
   /** Drop a session. Saved comments on disk are left alone. */
   app.delete('/api/cleanup/:repoId', (req, res) => {
     sessions.delete(req.params.repoId);
@@ -1175,6 +1467,9 @@ function startServer(options = {}) {
       }
       resolve(server);
     });
+    // A background session must not outlive the server that started it.
+    server.stopAgents = app.locals.stopAgents;
+    server.on('close', () => { app.locals.stopAgents(); });
     server.on('error', reject);
   });
 }