git-reviewer 2.14.1 → 2.16.0

package/lib/answerer.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+const { updateSavedComments } = require('./store');
+const { watchComments } = require('./watch');
+const { announce, listAgents, watchAgents } = require('./presence');
+const { mintKey } = require('./comments');
+const { awaitingAnswer, newReviewerMessages, appendReply, lastAuthor, followUpIdentity } = require('./threads');
+const { questionFor } = require('./claude-background');
+
+/**
+ * Keep a review's threads answered by a background Claude Code session.
+ *
+ * Everything the reviewer says -- a new comment, a reply in a thread, from
+ * this tab or any other -- reaches the session through the comments file,
+ * and every answer goes back the same way, as a follow-up written `by:
+ * claude`. Nothing here talks to the page directly except the text of an
+ * answer still being written, which is not worth a file write per word.
+ *
+ * Threads already waiting when it connects are answered first, oldest first.
+ */
+
+/** The reviewer's messages in a thread, by identity: the comment, and their follow-ups. */
+function reviewerMessages(comment) {
+  return new Set([
+    `comment:${comment.key}`,
+    ...(comment.followUps ?? []).filter(followUp => !followUp.by).map(followUpIdentity)
+  ]);
+}
+
+class Answerer extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} options.reviewsDir
+   * @param {string} options.repoPath
+   * @param {import('./claude-background').BackgroundSession} options.session
+   * @param {{id: string, title: string|null}} options.claudeSession the session being asked
+   * @param {string} [options.agent] the name answers are written under
+   */
+  constructor({ reviewsDir, repoPath, session, claudeSession, agent = 'claude' }) {
+    super();
+    this.reviewsDir = reviewsDir;
+    this.repoPath = repoPath;
+    this.session = session;
+    this.claudeSession = claudeSession;
+    this.agent = agent;
+
+    /** @type {import('./comments').Comment[]|null} */
+    this.known = null;
+    /** @type {Array<{key: string, force: boolean}>} */
+    this.queue = [];
+    /** @type {{key: string, asked: Set<string>}|null} */
+    this.inFlight = null;
+    this.stopped = false;
+
+    this.presence = announce(reviewsDir, repoPath, {
+      kind: 'background',
+      agent,
+      session: claudeSession.id,
+      title: claudeSession.title
+    });
+
+    session.on('session', () => this.emit('status', this.status()));
+    session.on('working', ({ key }) => this.presence.update({ working: [key] }));
+    session.on('partial', ({ key, text }) => this.emit('partial', { key, text }));
+    session.on('answer', ({ key, text, session: answeredBy }) => this.onAnswer(key, text, answeredBy));
+    session.on('failed', ({ key, message }) => {
+      this.inFlight = null;
+      this.presence.update({ working: [] });
+      this.emit('failed', { key, message });
+      this.emit('status', this.status());
+      this.dispatch();
+    });
+    session.on('exit', ({ message, fatal }) => {
+      if (message) this.emit('failed', { key: null, message });
+      // Claude Code could not even be started: say so once and disconnect,
+      // rather than show "connected" while every question fails the same way.
+      if (fatal) this.stop().then(() => this.emit('stopped'));
+    });
+
+    this.watcher = watchComments(reviewsDir, repoPath, state => this.onComments(state.comments));
+    // Threads held back while a live session was answering are this one's
+    // again when it leaves; nothing else would prompt another look.
+    this.agentsWatcher = watchAgents(reviewsDir, repoPath, () => this.dispatch());
+  }
+
+  /** @param {import('./comments').Comment[]} comments */
+  onComments(comments) {
+    if (this.stopped) return;
+    if (this.known === null) {
+      for (const comment of awaitingAnswer(comments)) this.enqueue(comment.key);
+    } else {
+      for (const { comment } of newReviewerMessages(this.known, comments)) this.enqueue(comment.key);
+    }
+    this.known = comments;
+    this.dispatch();
+  }
+
+  enqueue(key, force = false) {
+    const queued = this.queue.find(item => item.key === key);
+    if (queued) {
+      queued.force ||= force;
+      return;
+    }
+    this.queue.push({ key, force });
+  }
+
+  async dispatch() {
+    if (this.stopped || this.inFlight || this.queue.length === 0 || this.known === null) return;
+
+    // An agent answering live, in the reviewer's own terminal, takes
+    // precedence. Two agents answering one thread is noise, and the live one
+    // is the one somebody started on purpose.
+    const live = (await listAgents(this.reviewsDir, this.repoPath).catch(() => []))
+      .some(agent => agent.kind === 'channel');
+    if (live || this.inFlight || this.stopped) return;
+
+    while (this.queue.length > 0) {
+      const { key, force } = this.queue.shift();
+      const comment = this.known.find(entry => entry.key === key);
+      // Gone, or answered by somebody else in the meantime.
+      if (!comment || (!force && lastAuthor(comment) !== null)) continue;
+
+      this.inFlight = { key, asked: reviewerMessages(comment) };
+      this.session.ask(key, questionFor(comment));
+      this.emit('status', this.status());
+      return;
+    }
+    this.emit('status', this.status());
+  }
+
+  async onAnswer(key, text, answeredBy) {
+    const asked = this.inFlight?.key === key ? this.inFlight.asked : new Set();
+    let askAgain = false;
+
+    try {
+      await updateSavedComments(this.reviewsDir, this.repoPath, current => {
+        const thread = current.comments.find(comment => comment.key === key);
+        if (!thread) return null; // deleted while it was being answered
+        // Something the reviewer added while the answer was being written
+        // was not part of the question, so the thread is asked again --
+        // with everything, this answer included -- once this one is posted.
+        askAgain = [...reviewerMessages(thread)].some(identity => !asked.has(identity));
+        return {
+          comments: appendReply(current.comments, key, {
+            key: mintKey(),
+            text,
+            timestamp: new Date().toISOString(),
+            by: this.agent,
+            ...(answeredBy ? { session: answeredBy } : {})
+          })
+        };
+      });
+    } catch (error) {
+      this.emit('failed', { key, message: `Could not save the answer: ${error.message}` });
+    }
+
+    this.inFlight = null;
+    await this.presence.update({ working: [] });
+    if (askAgain) this.enqueue(key, true);
+    // Said even when nothing else is queued: the page shows "answering…"
+    // until it hears this thread is no longer being worked on.
+    this.emit('status', this.status());
+    this.dispatch();
+  }
+
+  status() {
+    return {
+      kind: 'background',
+      agent: this.agent,
+      session: this.claudeSession.id,
+      title: this.claudeSession.title,
+      answeringIn: this.session.answeringSession,
+      forked: this.session.fork,
+      working: this.inFlight?.key ?? null,
+      queued: this.queue.map(item => item.key)
+    };
+  }
+
+  async stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.watcher.close();
+    this.agentsWatcher.close();
+    await this.session.stop();
+    await this.presence.close();
+  }
+}
+
+module.exports = { Answerer };

package/lib/changes.js

@@ -12,8 +12,14 @@
  * @typedef {object} ChangedFile
  * @property {string} path repo-relative path
  * @property {'A'|'M'|'D'|'R'|'B'} status
+ * @property {boolean} [directory] a folded, wholly untracked directory
+ * @property {number} [fileCount] untracked files represented by that directory
  */
 
+// Keep a new source folder reviewable file by file, while hundreds of
+// untracked files take one row instead of pushing tracked edits off screen.
+const UNTRACKED_DIRECTORY_LIMIT = 200;
+
 /**
  * Unquotes git's octal-escaped, C-quoted filename strings (e.g. "\"caf\\303\\251.txt\"" -> "café.txt").
  *
@@ -136,30 +142,101 @@ function parseCommitFilePath(raw) {
  * most- to least-specific for that reason.
  *
  * @param {import('simple-git').StatusResult} status
+ * @param {string[]} [untrackedDirectories] directory entries from Git's normal untracked status
  * @returns {ChangedFile[]}
  */
-function collectWorkingChanges(status) {
+function collectWorkingChanges(status, untrackedDirectories = []) {
+  const directories = new Set(untrackedDirectories.map(unquoteGitPath).filter(p => p?.endsWith('/')));
+  const directoryOf = new Map();
+  const counts = new Map();
+
+  for (const rawPath of status?.not_added ?? []) {
+    const filePath = unquoteGitPath(rawPath);
+    if (!filePath || directoryOf.has(filePath)) continue;
+    // Check path components, not every directory against every file. The
+    // trailing slash also keeps output/ separate from output-neighbor/.
+    for (let slash = filePath.indexOf('/'); slash !== -1; slash = filePath.indexOf('/', slash + 1)) {
+      const directory = filePath.slice(0, slash + 1);
+      if (!directories.has(directory)) continue;
+      directoryOf.set(filePath, directory);
+      counts.set(directory, (counts.get(directory) ?? 0) + 1);
+      break;
+    }
+  }
+
   const buckets = [
     [status?.renamed ?? [], 'R'],
     [status?.deleted ?? [], 'D'],
     [status?.created ?? [], 'A'],
-    [status?.not_added ?? [], 'A'],
+    [status?.not_added ?? [], 'A', true],
     [status?.modified ?? [], 'M']
   ];
 
   const seen = new Map();
+  const untrackedPaths = new Set();
 
-  for (const [files, letter] of buckets) {
+  for (const [files, letter, untracked] of buckets) {
     for (const entry of files) {
       // `renamed` holds `{ from, to }`; every other bucket holds plain strings.
       const rawPath = typeof entry === 'string' ? entry : entry?.to;
       const filePath = unquoteGitPath(rawPath);
       if (!filePath || seen.has(filePath)) continue;
+      const directory = untracked ? directoryOf.get(filePath) : null;
+      const fileCount = counts.get(directory) ?? 0;
+      if (fileCount > UNTRACKED_DIRECTORY_LIMIT) {
+        if (!seen.has(directory)) {
+          seen.set(directory, { path: directory, status: 'A', directory: true, fileCount });
+          untrackedPaths.add(directory);
+        }
+        continue;
+      }
       seen.set(filePath, { path: filePath, status: letter });
+      if (untracked) untrackedPaths.add(filePath);
     }
   }
 
-  return [...seen.values()];
+  // Put tracked edits on screen first without changing status precedence.
+  // The source bucket matters: a staged addition also has status A.
+  const files = [...seen.values()];
+  return [
+    ...files.filter(file => !untrackedPaths.has(file.path)),
+    ...files.filter(file => untrackedPaths.has(file.path))
+  ];
+}
+
+/**
+ * Git's normal status identifies wholly untracked directories; its all
+ * status supplies the files to count and keep individually in small ones.
+ * Turning untracked files off must avoid enumerating them in the first place.
+ * @param {import('simple-git').SimpleGit} git
+ * @param {boolean} [untracked]
+ * @returns {Promise<ChangedFile[]>}
+ */
+async function collectWorkingTreeChanges(git, untracked = true) {
+  if (!untracked) return collectWorkingChanges(await git.status(['--untracked-files=no']));
+  const status = await git.status(['--untracked-files=normal']);
+  const directories = (status.not_added ?? []).filter(p => unquoteGitPath(p).endsWith('/'));
+  if (!directories.length) return collectWorkingChanges(status);
+  return collectWorkingChanges(await git.status(['--untracked-files=all']), directories);
+}
+
+/** Explain the visible rows and the files represented by folded directories. */
+function describeWorkingChanges(files, untracked = true) {
+  const directories = files.filter(file => file.directory);
+  const count = files.length - directories.length;
+  const headline = `Found ${count} changed file${count === 1 ? '' : 's'}`;
+  if (!untracked) {
+    const changes = count ? headline : 'No tracked changes';
+    return `${changes} — untracked files hidden`;
+  }
+  const total = directories.reduce((sum, file) => sum + file.fileCount, 0);
+  const summary = directories.length
+    ? `; ${directories.length} folder${directories.length === 1 ? '' : 's'} folded (${total.toLocaleString('en-US')} untracked files)`
+    : '';
+  const folded = directories.map(file =>
+    `${file.path} holds ${file.fileCount.toLocaleString('en-US')} untracked files; individual files are not listed.`
+  ).join(' ');
+  return headline + summary + (folded ? `. ${folded}` : '');
 }
 
 /**
@@ -287,6 +364,8 @@ async function collectStagedChanges(git) {
 module.exports = {
   collectStagedChanges,
   collectWorkingChanges,
+  collectWorkingTreeChanges,
+  describeWorkingChanges,
   collectCommitChanges,
   classifyCommitFile,
   unquoteGitPath,

package/lib/channel.js

@@ -0,0 +1,286 @@
+'use strict';
+
+const { updateSavedComments, readSavedComments } = require('./store');
+const { watchComments } = require('./watch');
+const { announce } = require('./presence');
+const { mintKey, isKey } = require('./comments');
+const { awaitingAnswer, newReviewerMessages, appendReply, describeThread, lastAuthor } = require('./threads');
+
+/**
+ * `reviewer channel`: a Claude Code channel for one repository's review.
+ *
+ * Claude Code runs this as an MCP server over stdio, and with channels
+ * enabled for it (`--dangerously-load-development-channels server:reviewer`
+ * during the research preview) it may push messages into the running
+ * session. Every comment the reviewer writes, and every reply they add in a
+ * thread, is pushed as one; the session answers by calling `reply`, which
+ * writes the answer into the thread, where the page shows it within a
+ * second. The session is the one the reviewer chose -- `reviewer connect`
+ * resumes the session that wrote the code -- so the answers come from the
+ * agent that knows why it wrote what it wrote.
+ *
+ * The protocol is spoken directly: MCP is JSON-RPC 2.0, one message per line,
+ * and this server needs four methods of it. The SDK would bring seventeen
+ * dependencies and a second major of express into a package that has three
+ * (#4).
+ */
+
+const PROTOCOL_VERSION = '2025-11-25';
+
+// At most this many waiting threads are pushed one by one when the session
+// connects; the rest are summarised, so connecting to an old review with
+// fifty open threads does not bury the session.
+const BACKLOG_ONE_BY_ONE = 8;
+
+/** @param {string} repoPath */
+function instructionsFor(repoPath) {
+  return [
+    `reviewer is a local code review tool. While this server is connected, every comment a reviewer leaves on`,
+    `the changes in ${repoPath}, and every reply they add to a thread, arrives as a`,
+    '<channel source="reviewer" key="..." file="..." line="..."> message holding the thread so far.',
+    '',
+    'Answer each one by calling the reply tool with its key. Your reply is shown under the reviewer\'s',
+    'comment exactly as written: keep it short and direct; Markdown is fine. Answer from what you know about',
+    'why the code is the way it is, and read files when you need to check. Do not change files because of a',
+    'comment unless it explicitly asks you to make the change now; otherwise say what you would change. If',
+    'several arrive together, answer each one separately. list_comments shows what is still waiting.'
+  ].join('\n');
+}
+
+const TOOLS = [
+  {
+    name: 'reply',
+    description: 'Post a reply in a review comment thread. The reviewer sees it under their comment straight away.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'The key of the comment, from the channel message or list_comments' },
+        text: { type: 'string', description: 'The reply, in Markdown' }
+      },
+      required: ['key', 'text']
+    }
+  },
+  {
+    name: 'list_comments',
+    description: 'List the review\'s comment threads: by default only those whose last word is the reviewer\'s.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        all: { type: 'boolean', description: 'Include threads that already have an answer' }
+      }
+    }
+  }
+];
+
+/**
+ * A thread as the session is told about it.
+ *
+ * @param {import('./comments').Comment} comment
+ * @param {boolean} followUp whether this is a new reply in a thread rather than a new comment
+ */
+function channelMessage(comment, followUp) {
+  return {
+    content: [
+      followUp ? 'The reviewer replied in a comment thread:' : 'New review comment:',
+      '',
+      describeThread(comment),
+      '',
+      `Answer with the reply tool, key "${comment.key}".`
+    ].join('\n'),
+    meta: { key: comment.key, file: comment.file, line: String(comment.line) }
+  };
+}
+
+/**
+ * Run the channel until its input closes.
+ *
+ * @param {object} options
+ * @param {string} options.repoPath repository whose review this serves
+ * @param {string} options.reviewsDir
+ * @param {NodeJS.ReadableStream} [options.input]
+ * @param {NodeJS.WritableStream} [options.output]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string} [options.version]
+ * @param {string|null} [options.title] what the connected session is about, for the page
+ * @param {(line: string) => void} [options.log] diagnostics; stdout belongs to the protocol
+ * @returns {Promise<void>} settles when the input ends
+ */
+function runChannel({
+  repoPath,
+  reviewsDir,
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+  version = '0.0.0',
+  title = null,
+  log = line => process.stderr.write(`reviewer channel: ${line}\n`)
+}) {
+  const session = env.CLAUDE_CODE_SESSION_ID || null;
+  const send = message => output.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+  const notify = (method, params) => send({ method, params });
+
+  /** @type {import('./comments').Comment[]|null} */
+  let known = null;
+  let watcher = null;
+  let presence = null;
+  const working = new Set();
+
+  const setWorking = () => presence?.update({ working: [...working] });
+
+  const push = (comment, followUp) => {
+    notify('notifications/claude/channel', channelMessage(comment, followUp));
+    working.add(comment.key);
+  };
+
+  const start = () => {
+    if (watcher) return;
+    presence = announce(reviewsDir, repoPath, { kind: 'channel', agent: 'claude', session, title });
+    watcher = watchComments(reviewsDir, repoPath, state => {
+      const comments = state.comments;
+      if (known === null) {
+        const waiting = awaitingAnswer(comments);
+        waiting.slice(0, BACKLOG_ONE_BY_ONE).forEach(comment => push(comment, (comment.followUps ?? []).length > 0));
+        if (waiting.length > BACKLOG_ONE_BY_ONE) {
+          notify('notifications/claude/channel', {
+            content: `${waiting.length - BACKLOG_ONE_BY_ONE} more comment threads in this review are waiting for an answer. ` +
+              'Call list_comments to see them, and answer each with the reply tool.',
+            meta: { waiting: String(waiting.length - BACKLOG_ONE_BY_ONE) }
+          });
+        }
+      } else {
+        for (const { comment, followUp } of newReviewerMessages(known, comments)) push(comment, followUp !== null);
+      }
+      // A thread answered from somewhere else is no longer this session's to answer.
+      for (const key of working) {
+        const thread = comments.find(comment => comment.key === key);
+        if (!thread || lastAuthor(thread) !== null) working.delete(key);
+      }
+      known = comments;
+      setWorking();
+    }, { onError: error => log(`could not read the review: ${error.message}`) });
+  };
+
+  const tools = {
+    async reply({ key, text } = {}) {
+      if (!isKey(key)) return failure('key must be the key of a comment, from the channel message or list_comments.');
+      if (typeof text !== 'string' || text.trim() === '') return failure('text must be the reply to post.');
+
+      let found = false;
+      await updateSavedComments(reviewsDir, repoPath, current => {
+        const updated = appendReply(current.comments, key, {
+          key: mintKey(),
+          text: text.trim(),
+          timestamp: new Date().toISOString(),
+          by: 'claude',
+          ...(session ? { session } : {})
+        });
+        found = updated !== null;
+        return updated ? { comments: updated } : null;
+      });
+
+      // An unknown key fails out loud: a reply that silently went nowhere
+      // would read, to the session, exactly like one the reviewer received.
+      if (!found) return failure(`No comment with key "${key}" in this review. Call list_comments for the current ones.`);
+      working.delete(key);
+      setWorking();
+      return success('Posted. The reviewer can see it under their comment now.');
+    },
+
+    async list_comments({ all = false } = {}) {
+      const { comments } = await readSavedComments(reviewsDir, repoPath);
+      const shown = all ? comments : awaitingAnswer(comments);
+      const threads = shown.map(comment => ({
+        key: comment.key,
+        file: comment.file,
+        line: comment.line,
+        waiting: lastAuthor(comment) === null,
+        thread: describeThread(comment)
+      }));
+      return success(threads.length === 0
+        ? (all ? 'This review has no comments yet.' : 'Nothing is waiting for an answer.')
+        : JSON.stringify(threads, null, 2));
+    }
+  };
+
+  const handle = async message => {
+    const { id, method, params } = message;
+    const isRequest = id !== undefined && id !== null;
+
+    switch (method) {
+      case 'initialize':
+        return send({
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {}, experimental: { 'claude/channel': {} } },
+            serverInfo: { name: 'reviewer', title: 'reviewer', version },
+            instructions: instructionsFor(repoPath)
+          }
+        });
+      case 'notifications/initialized':
+        return start();
+      case 'ping':
+        return send({ id, result: {} });
+      case 'tools/list':
+        return send({ id, result: { tools: TOOLS } });
+      case 'tools/call': {
+        const tool = tools[params?.name];
+        if (!tool) return send({ id, error: { code: -32602, message: `Unknown tool: ${params?.name}` } });
+        try {
+          return send({ id, result: await tool(params.arguments ?? {}) });
+        } catch (error) {
+          return send({ id, result: failure(error.message) });
+        }
+      }
+      default:
+        // Including `server/discover`, the 2026-07-28 revision's replacement
+        // for `initialize`. Claude Code tries it first and, answered "method
+        // not found", falls back to `initialize` -- the handshake channels
+        // are documented against.
+        if (isRequest) send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+        return undefined;
+    }
+  };
+
+  return new Promise(resolve => {
+    let buffered = '';
+    let pending = Promise.resolve();
+    input.setEncoding?.('utf-8');
+    input.on('data', chunk => {
+      buffered += chunk;
+      let newline;
+      while ((newline = buffered.indexOf('\n')) >= 0) {
+        const line = buffered.slice(0, newline).trim();
+        buffered = buffered.slice(newline + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          send({ id: null, error: { code: -32700, message: 'Parse error' } });
+          continue;
+        }
+        // In order: a reply must not overtake the list it was based on.
+        pending = pending.then(() => handle(message)).catch(error => log(error.message));
+      }
+    });
+    input.on('end', async () => {
+      await pending;
+      watcher?.close();
+      await presence?.close();
+      resolve();
+    });
+  });
+}
+
+/** @param {string} text */
+function success(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+/** @param {string} text */
+function failure(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+module.exports = { runChannel, channelMessage, instructionsFor, TOOLS, PROTOCOL_VERSION };