git-reviewer 2.14.1 → 2.16.0

package/lib/presence.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const fs = require('fs');
+const fsp = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+
+const { repoKey } = require('./review');
+const { writeFileAtomic, isAlive } = require('./store');
+
+/**
+ * Which agents are connected to a review right now.
+ *
+ * An agent answering in a review's threads may live in another process -- a
+ * Claude Code session running `reviewer channel` -- or inside the server
+ * itself. Either way it leaves a small file here saying who it is and what it
+ * is working on, refreshes it while it lives, and removes it when it stops.
+ * The page shows those files as "Claude is connected" and "answering…", which
+ * is the difference between a reply that is coming and silence.
+ *
+ * A file is trusted only while its process is alive and its heartbeat is
+ * recent, so an agent killed without the chance to clean up drops out of the
+ * list on its own instead of claiming to be connected forever.
+ */
+
+const HEARTBEAT_MS = 10000;
+const STALE_MS = 30000;
+const POLL_MS = 3000;
+
+/**
+ * @typedef {object} AgentPresence
+ * @property {string} id
+ * @property {string} repoPath
+ * @property {'channel'|'background'|'watch'} kind how it is connected
+ * @property {string} agent who answers, e.g. `claude`
+ * @property {string|null} session the agent's own session id, when known
+ * @property {string|null} title what that session is about, when known
+ * @property {number} pid
+ * @property {string} startedAt
+ * @property {string} heartbeatAt
+ * @property {string[]} working keys of threads it has been asked and not yet answered
+ */
+
+/** @param {string} reviewsDir @param {string} repoPath */
+function agentsDir(reviewsDir, repoPath) {
+  return path.join(reviewsDir, 'agents', repoKey(repoPath));
+}
+
+/**
+ * Announce an agent and keep the announcement fresh until `close()`.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @param {Omit<AgentPresence, 'id'|'repoPath'|'pid'|'startedAt'|'heartbeatAt'|'working'> & {working?: string[]}} info
+ */
+function announce(reviewsDir, repoPath, info) {
+  const id = crypto.randomBytes(6).toString('base64url');
+  const dir = agentsDir(reviewsDir, repoPath);
+  const file = path.join(dir, `${id}.json`);
+  const startedAt = new Date().toISOString();
+  /** @type {AgentPresence} */
+  let record = {
+    id,
+    repoPath,
+    kind: info.kind,
+    agent: info.agent,
+    session: info.session ?? null,
+    title: info.title ?? null,
+    pid: process.pid,
+    startedAt,
+    heartbeatAt: startedAt,
+    working: info.working ?? []
+  };
+  let closed = false;
+  let writing = Promise.resolve();
+
+  const write = () => {
+    record = { ...record, heartbeatAt: new Date().toISOString() };
+    const snapshot = `${JSON.stringify(record, null, 2)}\n`;
+    writing = writing
+      .then(async () => {
+        if (closed) return;
+        await fsp.mkdir(dir, { recursive: true });
+        await writeFileAtomic(file, snapshot);
+      })
+      .catch(() => {});
+    return writing;
+  };
+
+  const heartbeat = setInterval(write, HEARTBEAT_MS);
+  heartbeat.unref();
+
+  // A synchronous last word, for an exit that gives no time for anything else.
+  const removeNow = () => {
+    try {
+      fs.rmSync(file, { force: true });
+    } catch {
+      /* nothing more can be done on the way out */
+    }
+  };
+  process.on('exit', removeNow);
+
+  return {
+    id,
+    ready: write(),
+    /** @param {Partial<AgentPresence>} fields */
+    update(fields) {
+      record = { ...record, ...fields };
+      return write();
+    },
+    get record() {
+      return record;
+    },
+    async close() {
+      closed = true;
+      clearInterval(heartbeat);
+      process.off('exit', removeNow);
+      await writing;
+      await fsp.rm(file, { force: true });
+    }
+  };
+}
+
+/**
+ * The agents connected to a review, live ones only.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @param {object} [options]
+ * @param {number} [options.now]
+ * @returns {Promise<AgentPresence[]>} oldest first
+ */
+async function listAgents(reviewsDir, repoPath, { now = Date.now() } = {}) {
+  const dir = agentsDir(reviewsDir, repoPath);
+  let names;
+  try {
+    names = await fsp.readdir(dir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const agents = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    let record;
+    try {
+      record = JSON.parse(await fsp.readFile(file, 'utf-8'));
+    } catch {
+      continue; // being replaced right now, or not ours
+    }
+    const fresh = now - Date.parse(record.heartbeatAt) < STALE_MS;
+    if (fresh && isAlive(record.pid)) {
+      agents.push(record);
+    } else if (!isAlive(record.pid)) {
+      // Its process is gone and cannot clean up after itself any more.
+      await fsp.rm(file, { force: true }).catch(() => {});
+    }
+  }
+
+  return agents.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
+
+/**
+ * Hear about agents connecting, disconnecting and changing what they work on.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @param {(agents: AgentPresence[]) => void} onChange called at the start and on every change
+ * @param {object} [options]
+ * @param {number} [options.pollMs]
+ * @returns {{close: () => void, ready: Promise<void>}}
+ */
+function watchAgents(reviewsDir, repoPath, onChange, { pollMs = POLL_MS } = {}) {
+  const dir = agentsDir(reviewsDir, repoPath);
+  let closed = false;
+  let last;
+  let timer = null;
+
+  const check = async () => {
+    if (closed) return;
+    const agents = await listAgents(reviewsDir, repoPath).catch(() => []);
+    // Heartbeats move every ten seconds without anything a person would see
+    // changing, so they are left out of the comparison.
+    const signature = JSON.stringify(agents.map(({ heartbeatAt, ...agent }) => agent));
+    if (!closed && signature !== last) {
+      last = signature;
+      onChange(agents);
+    }
+  };
+
+  let watcher = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    watcher = fs.watch(dir, () => {
+      clearTimeout(timer);
+      timer = setTimeout(check, 25);
+    });
+    watcher.on('error', () => {
+      watcher?.close();
+      watcher = null;
+    });
+  } catch {
+    watcher = null;
+  }
+
+  // Also how an agent that died without cleaning up is noticed.
+  const poll = setInterval(check, pollMs);
+  poll.unref();
+
+  return {
+    ready: check(),
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      clearInterval(poll);
+      watcher?.close();
+    }
+  };
+}
+
+module.exports = { announce, listAgents, watchAgents, agentsDir, isAlive, HEARTBEAT_MS, STALE_MS };

package/lib/review.js

@@ -124,13 +124,15 @@ function reviewFilename(repoPath, generatedAt) {
  * @param {string} args.repoPath repository the review covers
  * @param {import('./comments').Comment[]} args.comments
  * @param {Date} args.generatedAt
+ * @param {string|null} [args.scope] an explanation of an explicitly restricted comparison
  * @returns {string}
  */
-function formatReview({ repoPath, comments, generatedAt }) {
+function formatReview({ repoPath, comments, generatedAt, scope = null }) {
   const sections = [
     '# Code Review\n',
     `Repository: ${repoPath}`,
     `Generated: ${generatedAt.toISOString()}`,
+    ...(scope ? [scope] : []),
     `Total Comments: ${comments.length}\n`
   ];
 

package/lib/sessions.js

@@ -35,7 +35,7 @@ class SessionStore {
    */
   constructor(generateId = () => crypto.randomBytes(8).toString('hex')) {
     this.generateId = generateId;
-    /** @type {Map<string, {repoPath: string, mode: ReviewMode, range: ReviewRange|null}>} */
+    /** @type {Map<string, {repoPath: string, mode: ReviewMode, range: ReviewRange|null, untracked?: boolean}>} */
     this.sessions = new Map();
   }
 
@@ -43,17 +43,21 @@ class SessionStore {
    * @param {string} repoPath absolute path of the opened repository
    * @param {ReviewMode} mode
    * @param {ReviewRange|null} [range] the two refs, for a commit-based review
+   * @param {boolean} [untracked] whether a working comparison includes untracked files
    * @returns {string} the new session id
    */
-  create(repoPath, mode, range = null) {
+  create(repoPath, mode, range = null, untracked = true) {
     const repoId = this.generateId();
-    this.sessions.set(repoId, { repoPath, mode, range });
+    this.sessions.set(repoId, {
+      repoPath, mode, range,
+      ...(mode === 'working' && untracked === false ? { untracked: false } : {})
+    });
     return repoId;
   }
 
   /**
    * @param {string} repoId
-   * @returns {{repoPath: string, mode: ReviewMode, range: ReviewRange|null}|undefined}
+   * @returns {{repoPath: string, mode: ReviewMode, range: ReviewRange|null, untracked?: boolean}|undefined}
    */
   get(repoId) {
     return this.sessions.get(repoId);

package/lib/store.js

@@ -2,8 +2,10 @@
 
 const fs = require('fs').promises;
 const path = require('path');
+const crypto = require('crypto');
 
 const { commentsFilename, legacyCommentsFilename, canonicalRepoPath } = require('./review');
+const { withKeys } = require('./comments');
 
 /**
  * Reading a repository's saved comments, whatever name they were written under.
@@ -74,10 +76,15 @@ async function readJson(file) {
  *
  * @param {string} reviewsDir
  * @param {string} repoPath
- * @returns {Promise<{comments: object[], mode: string|null, range: object|null, adopted: boolean}>}
+ * @returns {Promise<{comments: object[], mode: string|null, range: object|null, untracked?: boolean, adopted: boolean, lastUpdated: string|null}>}
  *   `mode` is null for a file written before it was recorded -- there is
  *   nothing on disk that says what was compared, and guessing would be
- *   worse than admitting it.
+ *   worse than admitting it. `lastUpdated` is null when the file carries
+ *   no stamp (or there is no file yet): it is the version token a caller
+ *   sends back on save so the server can tell a current writer from a
+ *   stale one (#107). Every comment and follow-up comes back with a `key`;
+ *   one saved before keys existed gets the key derived from its content (see
+ *   `withKeys`), the same on every read.
  * @throws {ReviewOwnershipError} when the current file names another repository
  */
 async function readSavedComments(reviewsDir, repoPath) {
@@ -90,15 +97,20 @@ async function readSavedComments(reviewsDir, repoPath) {
     if (!belongsTo(saved.repoPath, repoPath)) {
       throw new ReviewOwnershipError(repoPath, saved.repoPath);
     }
-    return { comments: saved.comments ?? [], mode: saved.mode ?? null, range: saved.range ?? null, adopted: false };
+    return {
+      comments: withKeys(saved.comments ?? []), mode: saved.mode ?? null, range: saved.range ?? null,
+      ...(saved.mode === 'working' && saved.untracked === false ? { untracked: false } : {}),
+      adopted: false,
+      lastUpdated: saved.lastUpdated ?? null
+    };
   }
 
   const legacyName = legacyCommentsFilename(repoPath);
-  if (legacyName === commentsFilename(repoPath)) return { comments: [], mode: null, range: null, adopted: false };
+  if (legacyName === commentsFilename(repoPath)) return { comments: [], mode: null, range: null, adopted: false, lastUpdated: null };
 
   const legacy = await readJson(path.join(reviewsDir, legacyName));
   if (legacy === null || !belongsTo(legacy.repoPath, repoPath)) {
-    return { comments: [], mode: null, range: null, adopted: false };
+    return { comments: [], mode: null, range: null, adopted: false, lastUpdated: null };
   }
 
   // Move it under the new name so the next read is a plain hit and the old
@@ -110,7 +122,278 @@ async function readSavedComments(reviewsDir, repoPath) {
     /* the comments are already in hand; renaming is housekeeping */
   }
 
-  return { comments: legacy.comments ?? [], mode: legacy.mode ?? null, range: legacy.range ?? null, adopted: true };
+  return {
+    comments: withKeys(legacy.comments ?? []), mode: legacy.mode ?? null, range: legacy.range ?? null,
+    ...(legacy.mode === 'working' && legacy.untracked === false ? { untracked: false } : {}),
+    adopted: true,
+    lastUpdated: legacy.lastUpdated ?? null
+  };
 }
 
-module.exports = { readSavedComments, ReviewOwnershipError, belongsTo };
+/**
+ * The `lastUpdated` stamp for a save that follows `previous`.
+ *
+ * Stamps are the version token for conditional saves (#107), so a new stamp
+ * must differ from the one it replaces even when two saves land inside the
+ * same millisecond -- otherwise a stale tab would look current by accident.
+ *
+ * @param {string|null} previous stamp currently on disk, if any
+ * @returns {string} ISO 8601 stamp strictly after `previous`
+ */
+function nextLastUpdated(previous) {
+  const parsed = previous ? Date.parse(previous) : NaN;
+  const stamp = Number.isNaN(parsed) ? Date.now() : Math.max(Date.now(), parsed + 1);
+  return new Date(stamp).toISOString();
+}
+
+// A lock older than this belongs to a writer that died holding it. Reading
+// and writing one small JSON file takes milliseconds; ten seconds is not a
+// writer that is merely slow. A lock whose writer is provably gone is not
+// waited on at all.
+const LOCK_STALE_MS = 10000;
+const LOCK_RETRY_MS = 15;
+const LOCK_TIMEOUT_MS = 5000;
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Whether a process is running.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: it exists, it just is not ours to signal.
+    return error.code === 'EPERM';
+  }
+}
+
+/**
+ * Whether creating a lock failed only because somebody else holds it.
+ *
+ * EEXIST everywhere. On Windows, also EPERM and EACCES: a file another
+ * process has just deleted lingers as "delete pending" while anyone still
+ * has it open, and creating one by the same name is refused until it is
+ * gone -- the lock is being released, not withheld. CI caught it: two
+ * writers in separate processes, and one of them died of EPERM.
+ *
+ * @param {NodeJS.ErrnoException} error
+ */
+function lockIsBusy(error) {
+  if (error.code === 'EEXIST') return true;
+  return process.platform === 'win32' && (error.code === 'EPERM' || error.code === 'EACCES');
+}
+
+/**
+ * Whether a lock has been abandoned: the process that wrote it has gone, or
+ * it has been held far longer than any write takes.
+ *
+ * @param {string} lock
+ * @returns {Promise<boolean>}
+ */
+async function isAbandoned(lock) {
+  const [content, stat] = await Promise.all([
+    fs.readFile(lock, 'utf-8').catch(() => null),
+    fs.stat(lock).catch(() => null)
+  ]);
+  if (content === null || !stat) return false; // released meanwhile: just try again
+  const owner = Number.parseInt(content, 10);
+  if (Number.isInteger(owner) && owner > 0 && !isAlive(owner)) return true;
+  return Date.now() - stat.mtimeMs > LOCK_STALE_MS;
+}
+
+/**
+ * Remove a lock whose writer died holding it, and say whether it was removed.
+ *
+ * Two waiters can both find the same lock abandoned. If each simply removed
+ * it, the second would remove the lock the first had just taken, and both
+ * would write at once -- the lost reply the lock exists to prevent. So
+ * breaking a lock is done under a lock of its own, and the one holding it
+ * looks again before removing anything. Nothing but a breaker removes a lock
+ * that is not its own, and there is one breaker at a time.
+ *
+ * @param {string} lock
+ * @returns {Promise<boolean>}
+ */
+async function breakAbandonedLock(lock) {
+  if (!(await isAbandoned(lock))) return false;
+
+  const breaker = `${lock}.break`;
+  try {
+    await (await fs.open(breaker, 'wx')).close();
+  } catch (error) {
+    if (!lockIsBusy(error)) throw error;
+    // Somebody else is breaking it. One who died doing so is cleared by age.
+    const stat = await fs.stat(breaker).catch(() => null);
+    if (stat && Date.now() - stat.mtimeMs > LOCK_STALE_MS) await fs.rm(breaker, { force: true });
+    return false;
+  }
+
+  try {
+    if (!(await isAbandoned(lock))) return false;
+    await fs.rm(lock, { force: true });
+    return true;
+  } finally {
+    await fs.rm(breaker, { force: true });
+  }
+}
+
+/**
+ * Run `task` holding the lock on `file`, against every process on the machine.
+ *
+ * The page is no longer the only writer. An agent answering in a thread
+ * writes the same file from another process -- `reviewer channel`, run by
+ * Claude Code -- and a read-modify-write from each, interleaved, loses one of
+ * them. The lock is a sibling file created with `wx`, which the operating
+ * system creates atomically or refuses, on every platform Node runs on, and
+ * which holds the writer's pid so a lock left by a process that died can be
+ * recognised as such.
+ *
+ * @template T
+ * @param {string} file
+ * @param {() => Promise<T>} task
+ * @returns {Promise<T>}
+ */
+async function withFileLock(file, task) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+  for (;;) {
+    try {
+      const handle = await fs.open(lock, 'wx');
+      try {
+        await handle.writeFile(`${process.pid}\n`);
+      } finally {
+        await handle.close();
+      }
+      break;
+    } catch (error) {
+      if (!lockIsBusy(error)) throw error;
+      if (error.code === 'EEXIST' && await breakAbandonedLock(lock)) continue;
+      if (Date.now() > deadline) {
+        if (error.code !== 'EEXIST') throw error;
+        throw new Error(`Timed out waiting for ${path.basename(lock)}; if no reviewer is running, delete it.`);
+      }
+      await sleep(LOCK_RETRY_MS);
+    }
+  }
+
+  try {
+    return await task();
+  } finally {
+    await fs.rm(lock, { force: true });
+  }
+}
+
+/**
+ * Replace `file` in one step, so no reader ever sees half of it.
+ *
+ * A reader in another process -- an agent watching the review -- would
+ * otherwise be able to catch the file truncated mid-write and parse nothing.
+ * Windows refuses to rename over a file another process has open for a
+ * moment, so that is retried briefly rather than failing the save.
+ *
+ * @param {string} file
+ * @param {string} content
+ */
+async function writeFileAtomic(file, content) {
+  const temporary = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  await fs.writeFile(temporary, content);
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await fs.rename(temporary, file);
+      return;
+    } catch (error) {
+      if (attempt < 20 && ['EPERM', 'EACCES', 'EBUSY'].includes(error.code)) {
+        await sleep(10);
+        continue;
+      }
+      await fs.rm(temporary, { force: true });
+      throw error;
+    }
+  }
+}
+
+// Writes from this process to one file go one at a time, so they queue here
+// instead of polling for the lock against each other.
+/** @type {Map<string, Promise<void>>} */
+const queues = new Map();
+
+function serialize(file, task) {
+  const previous = queues.get(file) ?? Promise.resolve();
+  const run = previous.then(task, task);
+  const tail = run.then(() => {}, () => {});
+  queues.set(file, tail);
+  tail.then(() => {
+    if (queues.get(file) === tail) queues.delete(file);
+  });
+  return run;
+}
+
+/**
+ * @typedef {object} SavedReview
+ * @property {import('./comments').Comment[]} comments keyed
+ * @property {string|null} mode
+ * @property {object|null} range
+ * @property {boolean} [untracked]
+ * @property {string|null} lastUpdated
+ */
+
+/**
+ * Change a repository's saved comments, safely against every other writer.
+ *
+ * Takes the lock, reads what is on disk now, and hands it to `update`, which
+ * returns the comments to write -- or null to write nothing, which is how a
+ * conditional save turns itself down. What it returns is written in one step
+ * with a `lastUpdated` strictly after the one it replaced. The scope fields
+ * (`mode`, `range`, `untracked`) are kept from disk unless `update` supplies
+ * them: a reply in a thread does not change what the review is of.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @param {(current: SavedReview) => ({comments: object[], scope?: {mode: string|null, range: object|null, untracked?: boolean}}|null|Promise<object|null>)} update
+ * @returns {Promise<{written: boolean, comments: object[], lastUpdated: string|null}>}
+ */
+async function updateSavedComments(reviewsDir, repoPath, update) {
+  const file = path.join(reviewsDir, commentsFilename(repoPath));
+
+  return serialize(file, async () => {
+    await fs.mkdir(reviewsDir, { recursive: true });
+
+    return withFileLock(file, async () => {
+      const current = await readSavedComments(reviewsDir, repoPath);
+      const change = await update(current);
+      if (!change) return { written: false, comments: current.comments, lastUpdated: current.lastUpdated };
+
+      const scope = change.scope ?? current;
+      const lastUpdated = nextLastUpdated(current.lastUpdated ?? null);
+      const data = {
+        repoPath,
+        lastUpdated,
+        mode: scope.mode ?? null,
+        range: scope.range ?? null,
+        ...(scope.mode === 'working' && scope.untracked === false ? { untracked: false } : {}),
+        comments: change.comments
+      };
+      await writeFileAtomic(file, `${JSON.stringify(data, null, 2)}\n`);
+
+      return { written: true, comments: change.comments, lastUpdated };
+    });
+  });
+}
+
+module.exports = {
+  readSavedComments,
+  updateSavedComments,
+  nextLastUpdated,
+  withFileLock,
+  writeFileAtomic,
+  isAlive,
+  ReviewOwnershipError,
+  belongsTo
+};