git-reviewer 2.15.0 → 2.16.0

package/lib/comments.js

@@ -1,21 +1,29 @@
 'use strict';
 
+const crypto = require('crypto');
+
 /**
  * The stored shape of a review comment.
  *
- * The client keeps extra bookkeeping on each comment (ids, collapsed state,
- * draft text). Only the fields below are written to disk, so a comment file
- * stays readable and stable across UI changes.
+ * The client keeps extra bookkeeping on each comment (diff positions, match
+ * state, draft text). Only the fields below are written to disk, so a comment
+ * file stays readable and stable across UI changes.
  */
 
 /**
  * @typedef {object} FollowUp
+ * @property {string} [key] stable identity, minted when it is written
  * @property {string} text
  * @property {string} [timestamp] ISO 8601
+ * @property {string} [by] who wrote it, when it was not the reviewer: an
+ *   agent answering in the thread, say `claude`. Absent means the reviewer,
+ *   which is what every follow-up written before this field existed was.
+ * @property {string} [session] the agent session that wrote it, when known
  */
 
 /**
  * @typedef {object} Comment
+ * @property {string} [key] stable identity, minted when the comment is created
  * @property {string} file repo-relative path
  * @property {number} line 1-based line number
  * @property {string} [lineContent] the line the comment is anchored to
@@ -24,6 +32,136 @@
  * @property {FollowUp[]} [followUps]
  */
 
+/**
+ * What a key looks like: short, and safe in a URL, a filename and an
+ * unquoted shell argument, because `reviewer reply <key>` is typed.
+ */
+const KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** A name in `by`: something a person would recognise in a thread. */
+const AUTHOR_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,39}$/;
+
+/** A session reference in `session`: an id, not prose. */
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
+/** @param {unknown} value */
+function isKey(value) {
+  return typeof value === 'string' && KEY_PATTERN.test(value);
+}
+
+/**
+ * A new random key: eight characters, 48 bits from `crypto`.
+ *
+ * Short on purpose. The comment file is meant to stay readable, the key is
+ * typed on a command line, and two collisions in one review would need tens
+ * of millions of comments.
+ *
+ * @returns {string}
+ */
+function mintKey() {
+  return crypto.randomBytes(6).toString('base64url');
+}
+
+/**
+ * The key a comment written without one has always had.
+ *
+ * Derived rather than random so that every reader -- a tab, an agent, `reviewer
+ * export` -- names the same comment the same way without anyone having to
+ * write the file first. The parts are what identified a comment before keys
+ * existed, plus how many earlier entries shared them, so two identical
+ * comments on one line still get two keys.
+ *
+ * @param {string[]} parts
+ * @returns {string}
+ */
+function derivedKey(parts) {
+  return crypto.createHash('sha256').update(parts.join('\u0000')).digest('base64url').slice(0, 8);
+}
+
+/**
+ * Give every comment and follow-up a key, keeping the ones they already have.
+ *
+ * Comments saved before keys existed are read through here, and so is
+ * anything posted by a client that does not send keys. Both get the derived
+ * key, so the same comment comes back with the same key on every read, and a
+ * script that re-posts the same list keeps its comments' identities rather
+ * than turning each save into a delete and an add.
+ *
+ * @template {Comment} T
+ * @param {T[]} comments
+ * @returns {T[]} new objects; the input is left alone
+ */
+function withKeys(comments) {
+  const occurrences = new Map();
+  const nth = identity => {
+    const n = occurrences.get(identity) ?? 0;
+    occurrences.set(identity, n + 1);
+    return String(n);
+  };
+
+  return comments.map(comment => {
+    const key = isKey(comment.key)
+      ? comment.key
+      : derivedKey(['comment', comment.file, String(comment.line), comment.text,
+        nth(JSON.stringify([comment.file, comment.line, comment.text]))]);
+
+    const keyed = { ...comment, key };
+    if (Array.isArray(comment.followUps)) {
+      keyed.followUps = comment.followUps.map(followUp => (isKey(followUp?.key)
+        ? followUp
+        : {
+          ...followUp,
+          key: derivedKey(['follow-up', key, followUp?.timestamp ?? '', followUp?.text ?? '',
+            followUp?.by ?? '', nth(JSON.stringify([key, followUp?.timestamp, followUp?.text, followUp?.by]))])
+        }));
+    }
+    return keyed;
+  });
+}
+
+/**
+ * Reduce a follow-up to the fields that get persisted.
+ *
+ * @param {object} followUp
+ * @param {string} where position, for the error message
+ * @returns {FollowUp}
+ * @throws {TypeError} when it is malformed
+ */
+function normalizeFollowUp(followUp, where) {
+  if (followUp === null || typeof followUp !== 'object' || Array.isArray(followUp)) {
+    throw new TypeError(`${where} must be an object`);
+  }
+  if (typeof followUp.text !== 'string' || followUp.text.trim() === '') {
+    throw new TypeError(`${where}.text must be a non-empty string`);
+  }
+
+  /** @type {FollowUp} */
+  const entry = {};
+  if (followUp.key !== undefined) {
+    if (!isKey(followUp.key)) throw new TypeError(`${where}.key must be 1-64 letters, digits, _ or -`);
+    entry.key = followUp.key;
+  }
+  entry.text = followUp.text;
+  if (followUp.timestamp) entry.timestamp = followUp.timestamp;
+
+  // Empty and absent are the same thing here -- the reviewer -- so only a
+  // real name is stored, and the file never says `"by": ""`.
+  if (followUp.by !== undefined && followUp.by !== null && followUp.by !== '') {
+    if (typeof followUp.by !== 'string' || !AUTHOR_PATTERN.test(followUp.by)) {
+      throw new TypeError(`${where}.by must be a short name, such as "claude"`);
+    }
+    entry.by = followUp.by;
+  }
+  if (followUp.session !== undefined && followUp.session !== null && followUp.session !== '') {
+    if (typeof followUp.session !== 'string' || !SESSION_PATTERN.test(followUp.session)) {
+      throw new TypeError(`${where}.session must be a session id`);
+    }
+    entry.session = followUp.session;
+  }
+
+  return entry;
+}
+
 /**
  * Reduce a client comment to the fields that get persisted.
  *
@@ -54,8 +192,12 @@ function normalizeComment(comment, index) {
   if (typeof comment.text !== 'string' || comment.text.trim() === '') {
     throw new TypeError(`${where}.text must be a non-empty string`);
   }
+  if (comment.key !== undefined && !isKey(comment.key)) {
+    throw new TypeError(`${where}.key must be 1-64 letters, digits, _ or -`);
+  }
 
   const normalized = {
+    ...(comment.key !== undefined ? { key: comment.key } : {}),
     file: comment.file,
     line: comment.line,
     lineContent: comment.lineContent,
@@ -67,11 +209,9 @@ function normalizeComment(comment, index) {
   }
 
   if (Array.isArray(comment.followUps) && comment.followUps.length > 0) {
-    normalized.followUps = comment.followUps.map(followUp => {
-      const entry = { text: followUp.text };
-      if (followUp.timestamp) entry.timestamp = followUp.timestamp;
-      return entry;
-    });
+    normalized.followUps = comment.followUps.map(
+      (followUp, i) => normalizeFollowUp(followUp, `${where}.followUps[${i}]`)
+    );
   }
 
   return normalized;
@@ -80,6 +220,10 @@ function normalizeComment(comment, index) {
 /**
  * Normalize a batch of comments.
  *
+ * Two comments claiming one key are refused: a key is how a reply finds its
+ * thread, and a reply that could land on either of two comments is the
+ * confidently-wrong outcome keys exist to rule out.
+ *
  * @param {object[]} comments
  * @returns {Comment[]}
  * @throws {TypeError} when `comments` is not an array or a comment is malformed
@@ -88,7 +232,18 @@ function normalizeComments(comments) {
   if (!Array.isArray(comments)) {
     throw new TypeError('comments must be an array');
   }
-  return comments.map((comment, index) => normalizeComment(comment, index));
+  const normalized = comments.map((comment, index) => normalizeComment(comment, index));
+
+  const seen = new Set();
+  normalized.forEach((comment, index) => {
+    if (comment.key === undefined) return;
+    if (seen.has(comment.key)) {
+      throw new TypeError(`comments[${index}].key "${comment.key}" is used by another comment`);
+    }
+    seen.add(comment.key);
+  });
+
+  return normalized;
 }
 
 /**
@@ -116,4 +271,14 @@ function groupByFile(comments) {
   ]);
 }
 
-module.exports = { normalizeComment, normalizeComments, groupByFile };
+module.exports = {
+  normalizeComment,
+  normalizeComments,
+  normalizeFollowUp,
+  groupByFile,
+  withKeys,
+  mintKey,
+  isKey,
+  KEY_PATTERN,
+  AUTHOR_PATTERN
+};

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 };