git-reviewer 2.14.1 → 2.16.0

package/lib/cli.js

@@ -2,6 +2,8 @@
 
 const path = require('path');
 
+const { KEY_PATTERN, AUTHOR_PATTERN } = require('./comments');
+
 /**
  * Command-line parsing for the `reviewer` command.
  *
@@ -15,6 +17,10 @@ function usage(name = 'git reviewer') {
 Usage:
   ${name} [repository] [options]
   ${name} export [repository] [--format json|prompt] [--file <path>]
+  ${name} connect [repository] [--session <id>] [--fork] [--list]
+  ${name} reply <key> <text | -> [--repo <path>] [--as <name>]
+  ${name} watch [repository]
+  ${name} channel [repository]
 
 One program, two names. git reviewer is the name the package is installed as
 -- git runs any git-<name> on your PATH as a subcommand -- and reviewer is the
@@ -38,14 +44,34 @@ Arguments:
 Commands:
   export            Print the saved review of a repository to stdout, for a
                     coding agent or another tool to consume.
+  connect           Resume the Claude Code session that worked in this
+                    repository with reviewer attached: every comment you
+                    write is sent to it, and it answers in the thread.
+                    --list shows the sessions; --session picks one.
+  reply             Post a reply in a comment thread, as an agent: the
+                    page shows it under the comment straight away. Use -
+                    as the text to read it from stdin.
+  watch             Print each new comment or reply from the reviewer as
+                    one JSON line, for an agent to follow and answer.
+  channel           The MCP server Claude Code runs for connect. Not
+                    something to run by hand.
 
 Options:
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --no-intro    Open the review without the first-run help
+      --no-untracked Exclude untracked files from working directory reviews
       --staged      Review only staged changes (HEAD vs index)
+      --json        Print one JSON line on stderr at startup instead of the banner
   -f, --format <f>  Export format: json (default) or prompt
       --file <path> Export comments for one repo-relative file
+      --session <id> connect: the Claude Code session to resume
+      --fork        connect: answer in a copy of the session
+      --list        connect: list this repository's sessions
+      --repo <path> reply: the repository (default: the current one)
+      --as <name>   reply: who the reply is from (default: claude inside
+                    Claude Code, agent elsewhere)
   -h, --help        Show this help
   -v, --version     Show the version
 
@@ -64,12 +90,17 @@ Examples:
       only the comments on one file
   ${name} export . --format prompt | claude -p "apply this review"
       hand over a review written earlier
+  ${name} connect
+      have the session that wrote the code answer your comments
 `;
 }
 
 /** Formats `reviewer export` can print. */
 const FORMATS = ['json', 'prompt'];
 
+/** Words that, first on the command line, name a subcommand. */
+const COMMANDS = ['export', 'connect', 'reply', 'watch', 'channel'];
+
 class UsageError extends Error {
   /** @param {string} message */
   constructor(message) {
@@ -80,13 +111,23 @@ class UsageError extends Error {
 
 /**
  * @typedef {object} CliOptions
- * @property {'serve'|'export'} command
+ * @property {'serve'|'export'|'connect'|'reply'|'watch'|'channel'} command
  * @property {string|null} repoPath absolute path, or null when not given
  * @property {number|null} port explicit port, or null to use the default
  * @property {boolean} open whether to launch a browser
+ * @property {boolean} noIntro skip the first-run help dialog
  * @property {boolean} staged whether to review only the index
+ * @property {boolean} untracked whether to include untracked files
+ * @property {boolean} json whether to print the startup info as one JSON line
  * @property {'json'|'prompt'} format for `export`
  * @property {string|null} file repo-relative file to export, or all files
+ * @property {string|null} session `connect`: Claude Code session id
+ * @property {boolean} fork `connect`: resume a copy of the session
+ * @property {boolean} list `connect`: list sessions instead of connecting
+ * @property {string|null} key `reply`: the comment to reply to
+ * @property {string|null} text `reply`: what to say
+ * @property {boolean} textFromStdin `reply`: the text is to be read from stdin
+ * @property {string|null} as `reply`: who it is from
  * @property {boolean} help
  * @property {boolean} version
  */
@@ -106,26 +147,54 @@ function parseArgs(argv, cwd = process.cwd()) {
     repoPath: null,
     port: null,
     open: true,
+    noIntro: false,
     staged: false,
+    untracked: true,
+    json: false,
     format: 'json',
     file: null,
+    session: null,
+    fork: false,
+    list: false,
+    key: null,
+    text: null,
+    textFromStdin: false,
+    as: null,
     help: false,
     version: false
   };
   let positional = null;
+  const positionals = [];
+  let replyRepo = null;
 
-  // A leading `export` is the subcommand. Anywhere else it is an ordinary
-  // path, so a directory that happens to be named `export` is still reviewable
-  // as `reviewer ./export`.
+  // A leading command word is the subcommand. Anywhere else it is an
+  // ordinary path, so a directory that happens to be named `export` is still
+  // reviewable as `reviewer ./export`.
   let rest = argv;
-  if (argv[0] === 'export') {
-    options.command = 'export';
+  if (COMMANDS.includes(argv[0])) {
+    options.command = argv[0];
     rest = argv.slice(1);
   }
 
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
 
+    // A reply is prose, and prose starts with "- " as often as anything:
+    // a Markdown list. After the key, a word that is not one of reply's own
+    // options is part of the reply, and `--` makes everything after it so.
+    if (options.command === 'reply') {
+      if (arg === '--') {
+        positionals.push(...rest.slice(i + 1));
+        break;
+      }
+      const ownOption = ['--repo', '--as', '-h', '--help', '-v', '--version'].includes(arg) ||
+        /^--(repo|as)=/.test(arg);
+      if (positionals.length > 0 && !ownOption) {
+        positionals.push(arg);
+        continue;
+      }
+    }
+
     switch (arg) {
       case '-h':
       case '--help':
@@ -141,10 +210,22 @@ function parseArgs(argv, cwd = process.cwd()) {
         options.open = false;
         break;
 
+      case '--no-intro':
+        options.noIntro = true;
+        break;
+
       case '--staged':
         options.staged = true;
         break;
 
+      case '--no-untracked':
+        options.untracked = false;
+        break;
+
+      case '--json':
+        options.json = true;
+        break;
+
       case '-p':
       case '--port': {
         const value = rest[++i];
@@ -167,6 +248,37 @@ function parseArgs(argv, cwd = process.cwd()) {
         break;
       }
 
+      case '--session': {
+        const value = rest[++i];
+        if (value === undefined || value.startsWith('-')) throw new UsageError('--session needs a session id');
+        options.session = value;
+        break;
+      }
+
+      case '--fork':
+        options.fork = true;
+        break;
+
+      case '--list':
+        options.list = true;
+        break;
+
+      case '--repo': {
+        const value = rest[++i];
+        if (value === undefined || value.startsWith('-')) throw new UsageError('--repo needs a repository path');
+        replyRepo = value;
+        break;
+      }
+
+      case '--as': {
+        const value = rest[++i];
+        if (value === undefined || !AUTHOR_PATTERN.test(value)) {
+          throw new UsageError('--as needs a short name, such as claude');
+        }
+        options.as = value;
+        break;
+      }
+
       default: {
         // Support --port=4500 as well as --port 4500.
         const inlinePort = arg.match(/^--port=(.*)$/);
@@ -187,10 +299,30 @@ function parseArgs(argv, cwd = process.cwd()) {
           break;
         }
 
+        const inlineRepo = arg.match(/^--repo=(.+)$/);
+        if (inlineRepo) {
+          replyRepo = inlineRepo[1];
+          break;
+        }
+
+        const inlineAs = arg.match(/^--as=(.*)$/);
+        if (inlineAs) {
+          if (!AUTHOR_PATTERN.test(inlineAs[1])) throw new UsageError('--as needs a short name, such as claude');
+          options.as = inlineAs[1];
+          break;
+        }
+
         if (arg.startsWith('-') && arg !== '-') {
           throw new UsageError(`Unknown option: ${arg}`);
         }
 
+        // `reply <key> <text...>` takes words, not a repository: the reply
+        // is everything after the key, so it need not be quoted.
+        if (options.command === 'reply') {
+          positionals.push(arg);
+          break;
+        }
+
         if (positional !== null) {
           throw new UsageError(`Unexpected argument: ${arg}`);
         }
@@ -204,6 +336,29 @@ function parseArgs(argv, cwd = process.cwd()) {
     options.repoPath = path.resolve(cwd, positional);
   }
 
+  if (options.command === 'reply') {
+    if (!options.help && !options.version) {
+      const [key, ...words] = positionals;
+      if (!key || !KEY_PATTERN.test(key)) throw new UsageError('reply needs the key of the comment to reply to');
+      const text = words.join(' ').trim();
+      if (text === '') throw new UsageError('reply needs the text of the reply, or - to read it from stdin');
+      options.key = key;
+      // `-` alone: the reply is on stdin, which suits an answer of several
+      // lines and quotes that a shell would otherwise have to survive.
+      options.text = text === '-' ? null : text;
+      options.textFromStdin = text === '-';
+    }
+    if (replyRepo !== null) options.repoPath = path.resolve(cwd, replyRepo);
+  } else if (replyRepo !== null) {
+    throw new UsageError('--repo is only valid with reviewer reply; name the repository directly');
+  }
+  if (options.as !== null && options.command !== 'reply') {
+    throw new UsageError('--as is only valid with reviewer reply');
+  }
+  for (const [flag, set] of [['--session', options.session !== null], ['--fork', options.fork], ['--list', options.list]]) {
+    if (set && options.command !== 'connect') throw new UsageError(`${flag} is only valid with reviewer connect`);
+  }
+
   if (options.file !== null && options.command !== 'export') {
     throw new UsageError('--file is only valid with reviewer export');
   }
@@ -211,7 +366,22 @@ function parseArgs(argv, cwd = process.cwd()) {
   if (options.staged && options.command !== 'serve') {
     throw new UsageError('--staged is only valid when serving a review');
   }
+  if (options.noIntro && options.command !== 'serve') {
+    throw new UsageError('--no-intro is only valid when serving a review');
+  }
+  if (!options.untracked && options.command !== 'serve') {
+    throw new UsageError('--no-untracked is only valid when serving a review');
+  }
 
+  if (options.json && options.command !== 'serve') {
+    throw new UsageError('--json is only valid when serving a review');
+  }
+  if (options.port !== null && options.command !== 'serve') {
+    throw new UsageError('--port is only valid when serving a review');
+  }
+  if (!options.open && options.command !== 'serve') {
+    throw new UsageError('--no-open is only valid when serving a review');
+  }
   return options;
 }
 
@@ -261,21 +431,28 @@ function parseFile(value, flag) {
  * @param {string} origin e.g. http://127.0.0.1:4500
  * @param {string|null} repoPath
  * @param {boolean} [staged]
+ * @param {boolean} [noIntro] add intro=0 so a fresh browser skips the first-run help
+ * @param {boolean} [untracked] include untracked files in working directory reviews
  * @returns {string}
  */
-function buildUrl(origin, repoPath, staged = false) {
-  if (!repoPath) return staged ? `${origin}/?staged=1` : origin;
-
-  // Slashes are left as slashes. They are legal in a query value -- RFC 3986
-  // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
-  // prominent line the command prints into %2F soup:
-  //
-  //   before  http://127.0.0.1:4500/?repo=%2FUsers%2Fyou%2Fwork%2Fapi
-  //   after   http://127.0.0.1:4500/?repo=/Users/you/work/api
-  //
-  // Everything else stays encoded, including the characters that would
-  // otherwise end the query and take the rest of the path with them.
-  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}${staged ? '&staged=1' : ''}`;
+function buildUrl(origin, repoPath, staged = false, noIntro = false, untracked = true) {
+  const params = [];
+  if (repoPath) {
+    // Slashes are left as slashes. They are legal in a query value -- RFC 3986
+    // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
+    // prominent line the command prints into %2F soup:
+    //
+    //   before  http://127.0.0.1:4500/?repo=%2FUsers%2Fyou%2Fwork%2Fapi
+    //   after   http://127.0.0.1:4500/?repo=/Users/you/work/api
+    //
+    // Everything else stays encoded, including the characters that would
+    // otherwise end the query and take the rest of the path with them.
+    params.push(`repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`);
+  }
+  if (staged) params.push('staged=1');
+  if (noIntro) params.push('intro=0');
+  if (!untracked) params.push('untracked=0');
+  return params.length === 0 ? origin : `${origin}/?${params.join('&')}`;
 }
 
 /**
@@ -300,4 +477,4 @@ function invokedAs(env, argv1) {
 
 const USAGE = usage();
 
-module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, usage, invokedAs };
+module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, COMMANDS, usage, invokedAs };

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/export.js

@@ -100,7 +100,7 @@ async function readGitPosition(repoPath) {
  *   records a different repository than the one asked for
  */
 async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
-  const { comments, mode, range } = await readSavedComments(reviewsDir, repoPath);
+  const { comments, mode, range, untracked } = await readSavedComments(reviewsDir, repoPath);
 
   if (comments.length === 0) throw new NoReviewError(repoPath);
 
@@ -121,7 +121,7 @@ async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
   // same object reference when no filter is given. `test/agent.test.js`
   // asserts that identity with `assert.equal`.
   const document = filterReviewDocument(
-    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode, range }),
+    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode, range, untracked }),
     { file }
   );