git-reviewer 2.15.0 → 2.17.0

package/server.js

@@ -14,14 +14,25 @@ const {
 } = require('./lib/paths');
 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, describeScope } = require('./lib/agent');
-const { readSavedComments, ReviewOwnershipError } = require('./lib/store');
+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 {
+  buildMatcher, searchDiffs, grepRepository, definesName, summarizeReferences, SearchError, SCOPES, MAX_RESULTS
+} = require('./lib/search');
 
 const DEFAULT_PORT = 4500;
 const DEFAULT_HOST = '127.0.0.1';
@@ -60,6 +71,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 +115,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 +146,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 +162,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 +814,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 +844,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. */
@@ -919,6 +991,11 @@ function createApp(options = {}) {
       sessions.get(repoId).foldedDirectories = new Map(
         files.filter(file => file.directory).map(file => [file.path, file.fileCount])
       );
+      // What a search of the review looks through: the files it shows, less
+      // folded directories and binaries, which have no lines to match.
+      sessions.get(repoId).files = files
+        .filter(file => !file.directory && file.status !== 'B')
+        .map(file => file.path);
       // 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.
@@ -1009,13 +1086,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);
@@ -1023,27 +1117,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,
-        ...(session.untracked === false ? { untracked: false } : {}),
-        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 });
     }
@@ -1055,8 +1169,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 });
@@ -1159,6 +1273,286 @@ 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) });
+  });
+
+  // A review's diffs are built once and searched as the reviewer types; this
+  // long is long enough for a burst of typing and short enough to notice an
+  // edit made since.
+  const SEARCH_CACHE_MS = 15000;
+
+  /**
+   * Every changed file's diff, as the page draws it, for searching.
+   *
+   * @param {object} session
+   * @returns {Promise<Array<{path: string, lines: object[]}>>}
+   */
+  async function diffsForSearch(session) {
+    const cached = session.searchCache;
+    if (cached && Date.now() - cached.at < SEARCH_CACHE_MS) return cached.files;
+
+    const git = gitFactory(session.repoPath);
+    const paths = session.files ?? [];
+    const files = [];
+    // A few at a time: a review of two hundred files should not start two
+    // hundred git processes at once.
+    for (let i = 0; i < paths.length; i += 8) {
+      const batch = await Promise.all(paths.slice(i, i + 8).map(async filePath => {
+        try {
+          const diffText = await diffForFile(git, session, filePath);
+          if (isBinaryDiff(diffText)) return null;
+          const content = await readFileForMode(session, filePath);
+          return { path: filePath, lines: parseDiff(diffText, content) };
+        } catch {
+          return null; // gone since the review was opened
+        }
+      }));
+      files.push(...batch.filter(Boolean));
+    }
+
+    session.searchCache = { at: Date.now(), files };
+    return files;
+  }
+
+  /**
+   * Search the review: every changed file at once, and with `scope=repo` the
+   * rest of the repository at the tree under review.
+   *
+   * `q` is the text; `mode` is contains, word, prefix, suffix or regex;
+   * `case=1` matches case; `scope` is changes (lines the change added or
+   * deleted), files (every line of the changed files) or repo. `symbol=1`
+   * is a references search: whole word, case-sensitive, and each result is
+   * marked as a definition or a use. Results say which side of the change
+   * they are on, and `diffIndex` is the line's position in the diff the
+   * page draws for that file.
+   */
+  app.get('/api/search/:repoId', async (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+
+    const pick = name => (typeof req.query[name] === 'string' ? req.query[name] : '');
+    const query = pick('q');
+    const symbol = pick('symbol') === '1';
+    const scope = pick('scope') || 'files';
+    const match = { mode: symbol ? 'word' : (pick('mode') || 'contains'), caseSensitive: symbol || pick('case') === '1' };
+    if (!SCOPES.includes(scope)) {
+      return res.status(400).json({ error: `Unknown scope "${scope}".` });
+    }
+
+    let matcher;
+    try {
+      matcher = buildMatcher(query, match);
+    } catch (error) {
+      if (error instanceof SearchError) return res.status(400).json({ error: error.message });
+      throw error;
+    }
+
+    try {
+      const started = Date.now();
+      const files = await diffsForSearch(session);
+      const found = searchDiffs(files, matcher, { changedOnly: scope === 'changes' });
+      let { results, truncated } = found;
+
+      if (scope === 'repo' && results.length < MAX_RESULTS) {
+        const elsewhere = await grepRepository({
+          repoPath: session.repoPath,
+          session,
+          query,
+          match,
+          matcher,
+          exclude: new Set(files.map(file => file.path)),
+          limit: MAX_RESULTS - results.length
+        });
+        results = results.concat(elsewhere.results);
+        truncated = truncated || elsewhere.truncated;
+      }
+
+      let summary = null;
+      if (symbol) {
+        for (const result of results) result.role = definesName(result.text, query) ? 'definition' : 'reference';
+        summary = summarizeReferences(results);
+      }
+
+      res.json({
+        query,
+        scope,
+        mode: match.mode,
+        caseSensitive: match.caseSensitive,
+        symbol,
+        results,
+        truncated,
+        files: new Set(results.map(result => result.file)).size,
+        searched: files.length,
+        ms: Date.now() - started,
+        summary
+      });
+    } catch (error) {
+      console.error('Search error:', error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+
   /** Drop a session. Saved comments on disk are left alone. */
   app.delete('/api/cleanup/:repoId', (req, res) => {
     sessions.delete(req.params.repoId);
@@ -1197,6 +1591,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);
   });
 }