git-reviewer 2.14.1 → 2.16.0

package/lib/claude-background.js

@@ -0,0 +1,316 @@
+'use strict';
+
+const { spawn: spawnProcess } = require('child_process');
+const { EventEmitter } = require('events');
+
+const { describeThread } = require('./threads');
+
+/**
+ * A Claude Code session, resumed in the background to answer review comments.
+ *
+ * The session that wrote the code is the one worth asking about it, so this
+ * resumes it -- by default as a copy, `--fork-session`, so the original
+ * transcript is left exactly as it was and can still be opened in a terminal
+ * while reviewer is using the copy. One `claude -p` process is kept running
+ * with stream-json on both ends: each question is a user message written to
+ * its stdin, and the answer streams back on stdout as it is written, which is
+ * what lets the page show it arriving instead of a spinner and then a wall of
+ * text.
+ *
+ * The copy can read the repository and nothing else. `--tools` limits it to
+ * Read, Grep and Glob, `--strict-mcp-config` keeps every MCP server the user
+ * has configured out of it -- including ones that can send mail -- and
+ * `dontAsk` turns anything that would need permission into a refusal, since
+ * nobody is there to answer a prompt. Answering a question about code needs
+ * nothing more, and a background process holding someone's credentials
+ * should not be able to do more.
+ */
+
+const TOOLS = 'Read,Grep,Glob';
+
+// Generous: a question can send the session reading through several files.
+const ANSWER_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * The message a thread is put to the session as.
+ *
+ * The instructions travel with every question rather than as a system
+ * prompt, because Claude Code records a session's system prompt once and
+ * reuses it on resume: anything appended at resume time would be dropped.
+ *
+ * @param {import('./comments').Comment} comment
+ * @returns {string}
+ */
+function questionFor(comment) {
+  return [
+    'A reviewer is going through the changes you made in this repository, in reviewer (a local code',
+    'review tool), and has left a comment on your code. Here is the thread:',
+    '',
+    describeThread(comment),
+    '',
+    'Reply to the reviewer\'s latest message. Your reply is posted under their comment exactly as you',
+    'write it, so write only the reply: short, direct, Markdown is fine. Answer from what you know about',
+    'why the code is the way it is, and read files if you need to check something. Do not change any',
+    'files; if a change is warranted, say what you would change.'
+  ].join('\n');
+}
+
+class BackgroundSession extends EventEmitter {
+  /**
+   * @param {object} options
+   * @param {string} options.sessionId Claude Code session to resume
+   * @param {string} options.cwd the directory that session ran in
+   * @param {boolean} [options.fork] answer in a copy of the session (the default) rather than in it
+   * @param {string} [options.name] display name for the copy, shown in Claude Code's /resume
+   * @param {string} [options.claude] the Claude Code executable
+   * @param {typeof spawnProcess} [options.spawn]
+   * @param {number} [options.answerTimeoutMs]
+   */
+  constructor({ sessionId, cwd, fork = true, name = null, claude = 'claude', spawn = spawnProcess, answerTimeoutMs = ANSWER_TIMEOUT_MS }) {
+    super();
+    this.sessionId = sessionId;
+    this.cwd = cwd;
+    this.fork = fork;
+    this.name = name;
+    this.claude = claude;
+    this.spawnProcess = spawn;
+    this.answerTimeoutMs = answerTimeoutMs;
+
+    /** The session answering: the copy's id once Claude Code reports it. */
+    this.answeringSession = fork ? null : sessionId;
+    /** @type {Array<{key: string, prompt: string}>} */
+    this.queue = [];
+    /** @type {{key: string, text: string, timer: NodeJS.Timeout, restarted: boolean}|null} */
+    this.current = null;
+    this.child = null;
+    this.stopped = false;
+    this.stderr = '';
+  }
+
+  /** The arguments `claude` is run with, so they can be shown and tested. */
+  args() {
+    const resume = this.answeringSession ?? this.sessionId;
+    return [
+      '-p',
+      '--input-format', 'stream-json',
+      '--output-format', 'stream-json',
+      '--verbose',
+      '--include-partial-messages',
+      '--resume', resume,
+      // Fork only the first time. Once the copy exists, a restart resumes
+      // the copy, so the answers so far stay in one conversation.
+      ...(this.fork && !this.answeringSession ? ['--fork-session'] : []),
+      ...(this.name && this.fork && !this.answeringSession ? ['--name', this.name] : []),
+      '--strict-mcp-config',
+      '--tools', TOOLS,
+      '--permission-mode', 'dontAsk'
+    ];
+  }
+
+  start() {
+    if (this.child || this.stopped) return;
+    this.stderr = '';
+    let child;
+    try {
+      child = this.spawnProcess(this.claude, this.args(), {
+        cwd: this.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: process.env,
+        windowsHide: true
+      });
+    } catch (error) {
+      // Some failures are thrown rather than emitted -- on Windows, a .cmd
+      // given without a shell is refused with EINVAL. Thrown from here, it
+      // would escape through `ask` into whatever called it; reported on the
+      // next tick it fails the same way an emitted one does.
+      process.nextTick(() => this.failToStart(error));
+      return;
+    }
+    this.child = child;
+
+    let buffered = '';
+    child.stdout.setEncoding('utf-8');
+    child.stdout.on('data', chunk => {
+      buffered += chunk;
+      let newline;
+      while ((newline = buffered.indexOf('\n')) >= 0) {
+        const line = buffered.slice(0, newline);
+        buffered = buffered.slice(newline + 1);
+        if (line.trim()) this.onLine(line);
+      }
+    });
+    child.stderr.setEncoding('utf-8');
+    child.stderr.on('data', chunk => {
+      // Kept for the error message if it exits; bounded, because a session
+      // can be chatty on stderr and this lives as long as the review.
+      this.stderr = (this.stderr + chunk).slice(-4000);
+    });
+    child.stdin.on('error', () => {}); // EPIPE when it has already gone; 'exit' reports why
+    child.on('error', error => this.onExit(null, null, error));
+    child.on('exit', (code, signal) => this.onExit(code, signal, null));
+  }
+
+  /** @param {string} line */
+  onLine(line) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return; // not ours to understand
+    }
+
+    if (event.type === 'system' && event.subtype === 'init' && event.session_id) {
+      if (this.answeringSession !== event.session_id) {
+        this.answeringSession = event.session_id;
+        this.emit('session', { session: event.session_id, model: event.model ?? null });
+      }
+      return;
+    }
+
+    if (!this.current) return;
+
+    if (event.type === 'stream_event') {
+      const inner = event.event;
+      if (inner?.type === 'message_start') {
+        // A turn that reads a file first produces text, a tool call, then
+        // more text. What is shown is the message being written now.
+        this.current.text = '';
+      } else if (inner?.type === 'content_block_delta' && inner.delta?.type === 'text_delta') {
+        this.current.text += inner.delta.text;
+        this.emit('partial', { key: this.current.key, text: this.current.text });
+      }
+      return;
+    }
+
+    if (event.type === 'result') {
+      const { key, timer } = this.current;
+      clearTimeout(timer);
+      this.current = null;
+      const text = typeof event.result === 'string' ? event.result.trim() : '';
+      if (event.is_error || event.subtype !== 'success' || text === '') {
+        this.emit('failed', { key, message: text || `Claude Code could not answer (${event.subtype ?? 'error'}).` });
+      } else {
+        this.emit('answer', { key, text, session: event.session_id ?? this.answeringSession });
+      }
+      this.next();
+    }
+  }
+
+  /** @param {Error & {code?: string}} error */
+  describeSpawnError(error) {
+    const where = process.platform === 'win32' ? ' (the full path of claude.exe)' : '';
+    return ['ENOENT', 'EINVAL'].includes(error.code)
+      ? `Could not run "${this.claude}": is Claude Code installed and on your PATH? Set REVIEWER_CLAUDE to its path otherwise${where}.`
+      : `Could not run "${this.claude}": ${error.message}`;
+  }
+
+  /** It could not be started: everything waiting fails, once, with why. */
+  failToStart(error) {
+    const message = this.describeSpawnError(error);
+    for (const { key } of this.queue.splice(0)) this.emit('failed', { key, message });
+    this.emit('exit', { code: null, signal: null, stderr: '', message, fatal: true });
+  }
+
+  onExit(code, signal, error) {
+    if (!this.child) return;
+    this.child = null;
+    const current = this.current;
+    if (current) clearTimeout(current.timer);
+    this.current = null;
+
+    if (this.stopped) {
+      this.emit('exit', { code, signal, stderr: this.stderr });
+      return;
+    }
+
+    const message = error
+      ? this.describeSpawnError(error)
+      : (this.stderr.trim().split('\n').slice(-3).join('\n') || `Claude Code exited (${signal ?? `code ${code}`}).`);
+
+    // A process that dies mid-answer gets one more go with the same
+    // question; one that cannot even start reports why and stops trying.
+    if (current && !current.restarted && !error) {
+      this.queue.unshift({ key: current.key, prompt: current.prompt, restarted: true });
+      this.start();
+      this.next();
+      return;
+    }
+    if (current) this.emit('failed', { key: current.key, message });
+    // `fatal`: it could not be started at all, so asking again would only
+    // fail the same way. Whoever owns this session should give up on it.
+    if (error) {
+      for (const { key } of this.queue.splice(0)) this.emit('failed', { key, message });
+    }
+    this.emit('exit', { code, signal, stderr: this.stderr, message, fatal: Boolean(error) });
+  }
+
+  /**
+   * Put a thread to the session. Questions are answered one at a time, in
+   * order: a turn's answer is matched to its question by being the next to
+   * finish, so a second question is not written until the first is done.
+   *
+   * @param {string} key comment key the answer belongs to
+   * @param {string} prompt
+   */
+  ask(key, prompt) {
+    if (this.stopped) return;
+    this.queue.push({ key, prompt, restarted: false });
+    this.start();
+    this.next();
+  }
+
+  next() {
+    if (this.current || !this.child || this.queue.length === 0) return;
+    const { key, prompt, restarted } = this.queue.shift();
+    const timer = setTimeout(() => {
+      // Nothing came back. Stop this process; the question fails, and the
+      // next one starts a fresh process on the same conversation.
+      if (this.current?.key !== key) return;
+      this.current = null;
+      this.emit('failed', { key, message: 'No answer after ten minutes; gave up on this one.' });
+      this.child?.kill();
+    }, this.answerTimeoutMs);
+    timer.unref();
+    this.current = { key, prompt, text: '', timer, restarted };
+    this.emit('working', { key });
+    this.child.stdin.write(`${JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } })}\n`);
+  }
+
+  /** Whether it is answering something or has questions waiting. */
+  get busy() {
+    return Boolean(this.current) || this.queue.length > 0;
+  }
+
+  /** Keys of the threads being answered or waiting, in order. */
+  get pending() {
+    return [...(this.current ? [this.current.key] : []), ...this.queue.map(item => item.key)];
+  }
+
+  /**
+   * Stop the process, now.
+   *
+   * Nothing it is in the middle of is wanted any more, and a turn can run
+   * for minutes -- left to finish, it would outlive the reviewer that started
+   * it. It is asked to stop straight away, and killed if it has not gone in
+   * three seconds.
+   *
+   * @returns {Promise<void>}
+   */
+  stop() {
+    this.stopped = true;
+    this.queue = [];
+    if (this.current) clearTimeout(this.current.timer);
+    const child = this.child;
+    if (!child) return Promise.resolve();
+    return new Promise(resolve => {
+      child.once('exit', () => resolve());
+      child.stdin.end();
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 3000).unref();
+      // Never hold up a shutdown on a process that will not say it is gone.
+      setTimeout(resolve, 5000).unref();
+    });
+  }
+}
+
+module.exports = { BackgroundSession, questionFor, TOOLS };

package/lib/claude-command.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * The Claude Code executable, as something `spawn` can start without a shell.
+ *
+ * Everywhere but Windows that is just the name: `spawn` searches the PATH.
+ * On Windows `spawn` runs only `.exe` and `.com` files without a shell, and
+ * refuses a `.cmd` outright (EINVAL, since Node 18.20.2 and 20.12.2). Claude
+ * Code installed through npm is reached through exactly that, a `claude.cmd`
+ * shim. The npm package carries the native `claude.exe` the shim starts,
+ * though, so that is found and run directly.
+ *
+ * A shell is never the answer here. The arguments include a session's title
+ * and an inline MCP config, and cmd.exe would read their quotes and
+ * metacharacters as its own.
+ *
+ * @param {string} command `claude`, or a path from REVIEWER_CLAUDE
+ * @param {object} [options] injectable for tests
+ * @param {string} [options.platform]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {(file: string) => boolean} [options.exists]
+ * @param {(file: string) => string} [options.read]
+ * @returns {string}
+ */
+function resolveClaudeCommand(command, {
+  platform = process.platform,
+  env = process.env,
+  exists = fs.existsSync,
+  read = file => fs.readFileSync(file, 'utf-8')
+} = {}) {
+  if (platform !== 'win32') return command;
+  const win = path.win32;
+
+  const candidates = [];
+  if (/[\\/]/.test(command)) {
+    candidates.push(command);
+  } else {
+    const extensions = win.extname(command) ? [''] : ['.exe', '.com', '.cmd', '.bat'];
+    for (const dir of (env.PATH ?? env.Path ?? '').split(';').filter(Boolean)) {
+      for (const extension of extensions) candidates.push(win.join(dir, `${command}${extension}`));
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (!exists(candidate)) continue;
+    const extension = win.extname(candidate).toLowerCase();
+    if (extension === '.exe' || extension === '.com') return candidate;
+    if (extension === '.cmd' || extension === '.bat') {
+      const target = shimTarget(candidate, { exists, read });
+      if (target) return target;
+    }
+  }
+
+  // Nothing better found: spawn fails, and the error says what to set.
+  return command;
+}
+
+/**
+ * The executable an npm `.cmd` shim starts.
+ *
+ * Where npm puts the package beside the shim, the binary is at a known
+ * place. Otherwise the shim names it: npm's shims start the target as
+ * `"%dp0%\path\to\target.exe"`, relative to the shim's own directory.
+ *
+ * @param {string} shim
+ * @param {{exists: (file: string) => boolean, read: (file: string) => string}} io
+ * @returns {string|null}
+ */
+function shimTarget(shim, { exists, read }) {
+  const win = path.win32;
+  const dir = win.dirname(shim);
+  const packaged = win.join(dir, 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe');
+  if (exists(packaged)) return packaged;
+
+  let text;
+  try {
+    text = read(shim);
+  } catch {
+    return null;
+  }
+  const named = text.match(/"%~?dp0%?\\([^"]+\.exe)"/i);
+  if (!named) return null;
+  const target = win.join(dir, named[1]);
+  return exists(target) ? target : null;
+}
+
+module.exports = { resolveClaudeCommand };

package/lib/claude-sessions.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const fsp = require('fs').promises;
+const os = require('os');
+const path = require('path');
+
+const { canonicalRepoPath } = require('./review');
+
+/**
+ * Finding the Claude Code sessions that worked in a repository.
+ *
+ * The session worth asking about a change is the one that made it: it read
+ * the code, chose the approach and remembers why. Claude Code keeps each
+ * session's transcript as a JSON-lines file under its config directory,
+ * filed by the working directory it ran in, and that is what is read here --
+ * only the first and last few kilobytes of each, for its working directory,
+ * its name and the first thing it was asked.
+ */
+
+// Enough of the head for the first prompt and the working directory, and of
+// the tail for a name given later in the session, without reading a
+// transcript that can run to tens of megabytes.
+const SLICE_BYTES = 64 * 1024;
+const PROMPT_CHARS = 240;
+
+/** Where Claude Code keeps its state: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */
+function claudeConfigDir(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(os.homedir(), '.claude');
+}
+
+/**
+ * The directory name Claude Code files a working directory's sessions under:
+ * the path with every character that is not a letter or a digit turned into
+ * `-`. `/home/you/work/api` becomes `-home-you-work-api`.
+ *
+ * @param {string} dir
+ */
+function projectDirName(dir) {
+  return dir.replace(/[^A-Za-z0-9]/g, '-');
+}
+
+/** A session id as Claude Code writes them: a UUID. */
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * @param {string} file
+ * @param {number} start
+ * @param {number} length
+ * @returns {Promise<string>}
+ */
+async function readSlice(file, start, length) {
+  const handle = await fsp.open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return buffer.subarray(0, bytesRead).toString('utf-8');
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * The records in a slice of a transcript. A slice cut mid-line yields a
+ * fragment at either end, which does not parse and is skipped.
+ *
+ * @param {string} text
+ * @returns {object[]}
+ */
+function records(text) {
+  const parsed = [];
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('{')) continue;
+    try {
+      parsed.push(JSON.parse(line));
+    } catch {
+      /* a fragment */
+    }
+  }
+  return parsed;
+}
+
+/**
+ * What a person typed, out of a transcript's user message -- not a tool
+ * result, and not the wrappers Claude Code puts around slash commands and
+ * reminders, which all open with a tag.
+ *
+ * @param {unknown} content
+ * @returns {string|null}
+ */
+function promptText(content) {
+  let text = null;
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content.find(block => block?.type === 'text' && typeof block.text === 'string')?.text ?? null;
+  }
+  if (!text) return null;
+  text = text.trim();
+  if (text === '' || text.startsWith('<') || text.startsWith('Caveat:')) return null;
+  const flat = text.replace(/\s+/g, ' ');
+  return flat.length > PROMPT_CHARS ? `${flat.slice(0, PROMPT_CHARS - 1)}…` : flat;
+}
+
+/**
+ * @typedef {object} ClaudeSession
+ * @property {string} id
+ * @property {string} cwd the directory it ran in
+ * @property {string|null} title the name it was given, or Claude Code's summary of it
+ * @property {string|null} firstPrompt
+ * @property {string|null} branch git branch when it started
+ * @property {string} updatedAt when it last wrote anything
+ */
+
+/**
+ * Read what a transcript says about itself.
+ *
+ * @param {string} file
+ * @returns {Promise<ClaudeSession|null>} null for a file that is not a session transcript
+ */
+async function describeSession(file) {
+  const id = path.basename(file, '.jsonl');
+  if (!SESSION_ID_PATTERN.test(id)) return null;
+
+  const stat = await fsp.stat(file);
+  const head = await readSlice(file, 0, SLICE_BYTES);
+  const tail = stat.size > SLICE_BYTES ? await readSlice(file, stat.size - SLICE_BYTES, SLICE_BYTES) : '';
+
+  let cwd = null;
+  let branch = null;
+  let firstPrompt = null;
+  let title = null;
+  let summary = null;
+
+  for (const record of [...records(head), ...records(tail)]) {
+    if (typeof record.cwd === 'string') cwd ??= record.cwd;
+    if (typeof record.gitBranch === 'string' && record.gitBranch !== '') branch ??= record.gitBranch;
+    if (!firstPrompt && record.type === 'user' && !record.isMeta && !record.isSidechain) {
+      firstPrompt = promptText(record.message?.content);
+    }
+    // Later records win: a session renamed halfway through goes by its new name.
+    if (record.type === 'custom-title' && typeof record.customTitle === 'string') title = record.customTitle;
+    if (record.type === 'summary' && typeof record.summary === 'string') summary = record.summary;
+  }
+
+  if (!cwd) return null;
+  return { id, cwd, title: title ?? summary ?? null, firstPrompt, branch, updatedAt: stat.mtime.toISOString() };
+}
+
+/** @param {string} child @param {string} parent */
+function isInside(child, parent) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Claude Code sessions that ran in a repository or any directory inside it,
+ * most recently active first.
+ *
+ * @param {string} repoPath
+ * @param {object} [options]
+ * @param {string} [options.configDir]
+ * @param {number} [options.limit]
+ * @returns {Promise<ClaudeSession[]>}
+ */
+async function listClaudeSessions(repoPath, { configDir = claudeConfigDir(), limit = 20 } = {}) {
+  const projects = path.join(configDir, 'projects');
+  const root = canonicalRepoPath(repoPath);
+  // The encoding loses information -- `/a/b-c` and `/a/b/c` share a name --
+  // so a matching directory is only a candidate. Each transcript's own
+  // working directory is what decides.
+  const prefixes = [...new Set([projectDirName(root), projectDirName(path.resolve(repoPath))])];
+
+  let dirs;
+  try {
+    dirs = (await fsp.readdir(projects, { withFileTypes: true }))
+      .filter(entry => entry.isDirectory() && prefixes.some(prefix => entry.name.startsWith(prefix)))
+      .map(entry => path.join(projects, entry.name));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const candidates = [];
+  for (const dir of dirs) {
+    for (const entry of await fsp.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+      const file = path.join(dir, entry.name);
+      const stat = await fsp.stat(file).catch(() => null);
+      if (stat) candidates.push({ file, mtimeMs: stat.mtimeMs });
+    }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const sessions = [];
+  for (const { file } of candidates) {
+    if (sessions.length >= limit) break;
+    const session = await describeSession(file).catch(() => null);
+    if (!session || !(session.firstPrompt || session.title)) continue;
+    if (!isInside(canonicalRepoPath(session.cwd), root)) continue;
+    sessions.push(session);
+  }
+  return sessions;
+}
+
+/**
+ * One session of a repository, by id -- or null, which is the answer for an
+ * id that is malformed, unknown, or belongs to another repository.
+ *
+ * @param {string} repoPath
+ * @param {string} id
+ * @param {object} [options]
+ * @param {string} [options.configDir]
+ * @returns {Promise<ClaudeSession|null>}
+ */
+async function findClaudeSession(repoPath, id, { configDir = claudeConfigDir() } = {}) {
+  if (typeof id !== 'string' || !SESSION_ID_PATTERN.test(id)) return null;
+  const sessions = await listClaudeSessions(repoPath, { configDir, limit: Infinity });
+  return sessions.find(session => session.id === id) ?? null;
+}
+
+module.exports = {
+  listClaudeSessions,
+  findClaudeSession,
+  describeSession,
+  claudeConfigDir,
+  projectDirName,
+  promptText,
+  SESSION_ID_PATTERN
+};