git-reviewer 2.15.0 → 2.17.0

package/lib/search.js

@@ -0,0 +1,319 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+/**
+ * Finding text across a review: every changed file at once, the way an IDE's
+ * find navigator searches a project rather than the open file.
+ *
+ * The question it is built for is the one a reviewer cannot answer from one
+ * file: "this function is new here -- where is it called, and where was it
+ * called before this change?" So every result says which side of the change
+ * it is on: a line this change added, one it deleted, unchanged code inside a
+ * changed file, or code in the rest of the repository the change did not
+ * touch. A references search goes one step further and tells definitions from
+ * uses, and says when a definition changed but its callers did not.
+ */
+
+// What counts as part of an identifier, for whole-word matching. `$` is in
+// it because JavaScript identifiers use it.
+const IDENT = 'A-Za-z0-9_$';
+const MODES = ['contains', 'word', 'prefix', 'suffix', 'regex'];
+const SCOPES = ['changes', 'files', 'repo'];
+
+const MAX_RESULTS = 2000;
+const MAX_PER_FILE = 300;
+const MAX_LINE = 2000;
+const MAX_RANGES = 20;
+
+/** A search that cannot run as asked; the message is for the person who typed it. */
+class SearchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SearchError';
+  }
+}
+
+const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The matcher for a query, as a global regular expression.
+ *
+ * @param {string} query
+ * @param {object} [options]
+ * @param {string} [options.mode] contains, word, prefix, suffix or regex
+ * @param {boolean} [options.caseSensitive]
+ * @returns {RegExp}
+ * @throws {SearchError}
+ */
+function buildMatcher(query, { mode = 'contains', caseSensitive = false } = {}) {
+  if (typeof query !== 'string' || query.trim() === '') throw new SearchError('Type something to search for.');
+  if (query.length > 500) throw new SearchError('That search is longer than 500 characters.');
+  if (!MODES.includes(mode)) throw new SearchError(`Unknown match mode "${mode}".`);
+
+  const literal = escapeRegExp(query);
+  const source = {
+    contains: literal,
+    word: `(?<![${IDENT}])${literal}(?![${IDENT}])`,
+    prefix: `(?<![${IDENT}])${literal}`,
+    suffix: `${literal}(?![${IDENT}])`,
+    regex: query
+  }[mode];
+
+  try {
+    return new RegExp(source, caseSensitive ? 'g' : 'gi');
+  } catch (error) {
+    throw new SearchError(`That is not a valid regular expression: ${error.message.replace(/^Invalid regular expression: /, '')}`);
+  }
+}
+
+/**
+ * Where a matcher matches on one line, as [start, end) pairs, so the page can
+ * mark exactly what matched. Very long lines -- minified bundles -- are
+ * searched only as far as MAX_LINE characters.
+ *
+ * @param {string} text
+ * @param {RegExp} matcher a global RegExp from buildMatcher
+ * @returns {Array<[number, number]>}
+ */
+function matchRanges(text, matcher) {
+  const line = text.length > MAX_LINE ? text.slice(0, MAX_LINE) : text;
+  const ranges = [];
+  matcher.lastIndex = 0;
+  let match;
+  while ((match = matcher.exec(line)) !== null) {
+    if (match[0].length === 0) {
+      matcher.lastIndex += 1; // an empty regex match would never advance
+      continue;
+    }
+    ranges.push([match.index, match.index + match[0].length]);
+    if (ranges.length >= MAX_RANGES) break;
+  }
+  return ranges;
+}
+
+/**
+ * Whether a line defines `name`, as far as one line can show it, in the
+ * languages people most often review: a function, class, method, type or
+ * variable declared under that name. A heuristic, and labelled as one in the
+ * page: a references search sorts by it, never hides by it.
+ *
+ * @param {string} text
+ * @param {string} name
+ * @returns {boolean}
+ */
+function definesName(text, name) {
+  const n = escapeRegExp(name);
+  const end = `(?![${IDENT}])`;
+  const declared = new RegExp(
+    `(?:^|[^${IDENT}.])(?:function\\*?|def|class|interface|type|struct|enum|trait|fn|func|const|let|var|val|module)\\s+${n}${end}`
+  );
+  const assigned = new RegExp(
+    `(?:^|[\\s{,;(])${n}\\s*[:=]\\s*(?:async\\s+)?(?:function\\b|\\([^)]*\\)\\s*=>|[A-Za-z_$][\\w$]*\\s*=>)`
+  );
+  const method = new RegExp(
+    `^\\s*(?:(?:public|private|protected|static|async|override|export|default|get|set)\\s+)*\\*?${n}\\s*\\([^)]*\\)\\s*(?::\\s*[^{]+)?\\{\\s*$`
+  );
+  return declared.test(text) || assigned.test(text) || method.test(text);
+}
+
+/**
+ * The side of the change a diff line is on.
+ *
+ * @param {'add'|'delete'|'unchanged'} type
+ * @returns {'added'|'deleted'|'context'}
+ */
+function sideOf(type) {
+  return type === 'add' ? 'added' : type === 'delete' ? 'deleted' : 'context';
+}
+
+/**
+ * Search the changed files of a review.
+ *
+ * @param {Array<{path: string, lines: Array<{type: string, oldLine: number|null, newLine: number|null, content: string}>}>} files
+ *   each changed file's diff, as the page draws it: every line of the file,
+ *   with what was added and deleted marked
+ * @param {RegExp} matcher
+ * @param {object} [options]
+ * @param {boolean} [options.changedOnly] only lines the change added or deleted
+ * @returns {{results: object[], truncated: boolean}}
+ */
+function searchDiffs(files, matcher, { changedOnly = false } = {}) {
+  const results = [];
+  let truncated = false;
+
+  for (const file of files) {
+    let inFile = 0;
+    for (let index = 0; index < file.lines.length; index++) {
+      const line = file.lines[index];
+      if (changedOnly && line.type !== 'add' && line.type !== 'delete') continue;
+      const ranges = matchRanges(line.content, matcher);
+      if (ranges.length === 0) continue;
+
+      if (results.length >= MAX_RESULTS || inFile >= MAX_PER_FILE) {
+        truncated = true;
+        if (results.length >= MAX_RESULTS) return { results, truncated };
+        break;
+      }
+      results.push({
+        file: file.path,
+        side: sideOf(line.type),
+        line: line.newLine ?? line.oldLine,
+        oldLine: line.oldLine,
+        newLine: line.newLine,
+        diffIndex: index,
+        text: line.content.slice(0, MAX_LINE),
+        ranges
+      });
+      inFile += 1;
+    }
+  }
+
+  return { results, truncated };
+}
+
+/**
+ * The git grep arguments for a query, as close to the matcher as git's own
+ * dialect allows. Whatever git finds is filtered through the real matcher
+ * afterwards, so git only has to be no narrower than it.
+ *
+ * @param {string} query
+ * @param {{mode: string, caseSensitive: boolean}} options
+ * @returns {string[]}
+ */
+function grepPattern(query, { mode, caseSensitive }) {
+  const literal = query.replace(/[.^$*+?()[\]{}|\\]/g, '\\$&');
+  const args = caseSensitive ? [] : ['-i'];
+  if (mode === 'contains' || mode === 'word' || mode === 'prefix' || mode === 'suffix') {
+    // A fixed-string search for the text is never narrower than any of
+    // these, and git does it fastest; the boundaries are checked in JS.
+    return [...args, '-F', '-e', query];
+  }
+  return [...args, '-E', '-e', mode === 'regex' ? query : literal];
+}
+
+/**
+ * Lines matching the query in the repository's files, on the reviewed side.
+ *
+ * Runs `git grep` against the exact tree under review -- the working tree, the
+ * index, or the head commit of a comparison -- and stops reading once it has
+ * enough, so a match in every file of a large repository costs the first
+ * MAX_RESULTS lines and no more.
+ *
+ * @param {object} options
+ * @param {string} options.repoPath
+ * @param {{mode: string, range: {head: string}|null}} options.session
+ * @param {string} options.query
+ * @param {{mode: string, caseSensitive: boolean}} options.match
+ * @param {RegExp} options.matcher
+ * @param {Set<string>} options.exclude paths already searched through their diff
+ * @param {number} [options.limit]
+ * @returns {Promise<{results: object[], truncated: boolean}>}
+ */
+function grepRepository({ repoPath, session, query, match, matcher, exclude, limit = MAX_RESULTS }) {
+  const where = session.mode === 'staged' ? ['--cached']
+    : session.range ? [session.range.head]
+      : [];
+  const rev = session.range && session.mode !== 'staged' ? session.range.head : null;
+  const args = ['grep', '-z', '-n', '-I', '--no-color', ...grepPattern(query, match), ...where, '--'];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd: repoPath, windowsHide: true });
+    const results = [];
+    const perFile = new Map();
+    let buffered = '';
+    let truncated = false;
+    let done = false;
+
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve({ results, truncated });
+    };
+
+    child.stdout.setEncoding('utf-8');
+    child.stdout.on('data', chunk => {
+      if (done) return;
+      buffered += chunk;
+      let newline;
+      while ((newline = buffered.indexOf('\n')) >= 0) {
+        const record = buffered.slice(0, newline);
+        buffered = buffered.slice(newline + 1);
+        const [location, lineNumber, ...rest] = record.split('\0');
+        if (lineNumber === undefined) continue;
+        const file = rev && location.startsWith(`${rev}:`) ? location.slice(rev.length + 1) : location;
+        if (exclude.has(file)) continue;
+        const text = rest.join('\0');
+        const ranges = matchRanges(text, matcher);
+        if (ranges.length === 0) continue;
+
+        const count = perFile.get(file) ?? 0;
+        if (count >= MAX_PER_FILE) {
+          truncated = true;
+          continue;
+        }
+        perFile.set(file, count + 1);
+        results.push({
+          file,
+          side: 'untouched',
+          line: Number(lineNumber),
+          oldLine: null,
+          newLine: Number(lineNumber),
+          diffIndex: null,
+          text: text.slice(0, MAX_LINE),
+          ranges
+        });
+        if (results.length >= limit) {
+          truncated = true;
+          child.kill();
+          finish();
+          return;
+        }
+      }
+    });
+    child.on('error', error => {
+      if (!done) {
+        done = true;
+        reject(error);
+      }
+    });
+    // git grep exits 1 when nothing matched, which is an answer, not a failure.
+    child.on('close', finish);
+  });
+}
+
+/**
+ * What a references search found, in the terms a reviewer asks it.
+ *
+ * @param {object[]} results with `role` set
+ * @returns {{definitions: number, added: number, removed: number, unchanged: number, warning: string|null}}
+ */
+function summarizeReferences(results) {
+  const uses = results.filter(result => result.role === 'reference');
+  const definitions = results.filter(result => result.role === 'definition');
+  const summary = {
+    definitions: definitions.length,
+    added: uses.filter(result => result.side === 'added').length,
+    removed: uses.filter(result => result.side === 'deleted').length,
+    unchanged: uses.filter(result => result.side === 'context' || result.side === 'untouched').length,
+    warning: null
+  };
+  const definitionChanged = definitions.some(result => result.side === 'added' || result.side === 'deleted');
+  if (definitionChanged && summary.unchanged > 0) {
+    summary.warning = `The definition changed, and ${summary.unchanged} ${summary.unchanged === 1 ? 'use was' : 'uses were'} left as they were. Check that they still fit.`;
+  }
+  return summary;
+}
+
+module.exports = {
+  buildMatcher,
+  matchRanges,
+  definesName,
+  searchDiffs,
+  grepRepository,
+  summarizeReferences,
+  SearchError,
+  MODES,
+  SCOPES,
+  MAX_RESULTS
+};

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, untracked?: boolean, 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) {
@@ -91,18 +98,19 @@ async function readSavedComments(reviewsDir, repoPath) {
       throw new ReviewOwnershipError(repoPath, saved.repoPath);
     }
     return {
-      comments: saved.comments ?? [], mode: saved.mode ?? null, range: saved.range ?? null,
+      comments: withKeys(saved.comments ?? []), mode: saved.mode ?? null, range: saved.range ?? null,
       ...(saved.mode === 'working' && saved.untracked === false ? { untracked: false } : {}),
-      adopted: 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
@@ -115,10 +123,277 @@ async function readSavedComments(reviewsDir, repoPath) {
   }
 
   return {
-    comments: legacy.comments ?? [], mode: legacy.mode ?? null, range: legacy.range ?? null,
+    comments: withKeys(legacy.comments ?? []), mode: legacy.mode ?? null, range: legacy.range ?? null,
     ...(legacy.mode === 'working' && legacy.untracked === false ? { untracked: false } : {}),
-    adopted: true
+    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
+};