git-reviewer 2.0.0 → 2.2.0

package/README.md

@@ -3,27 +3,34 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-163-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-206-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 ![Plain grey code lines on the left resolving into colored diff stripes, with threaded comment markers attached in the right margin](docs/banner.jpg)
 
-Review code before it becomes a pull request. `reviewer` opens any local git
-repository in your browser, shows what changed, and lets you leave inline
-comments with threaded follow-ups — against your working directory, without a
-branch, a remote, a push, or an account. Comments persist between sessions and
-survive the code moving underneath them, so you can review, edit, and come back
-tomorrow to a review that still points at the right lines. When you are done it
-writes a plain Markdown file you can paste anywhere.
+When an agent writes the code, reading it becomes the bottleneck — and the tool
+built for reading a diff, the pull request, wants a branch, a remote and a push
+you are not ready to make yet.
+
+`reviewer` gives you the pull-request view of your working directory instead:
+inline comments with threaded follow-ups, each attached to the exact line you
+mean, with no branch, no remote, no push and no account. Then it hands the
+marked-up review back to the agent to act on.
 
 ```bash
-cd ~/work/my-app
-npx git-reviewer .
+npx git-reviewer .                       # read the diff, leave comments
+npx git-reviewer export . --format prompt | claude -p "Apply this review."
 ```
 
-That starts a local server and opens your browser on the repository you named.
-There is nothing to install into the project, nothing to sign in to, and
-nothing leaves your machine.
+The first command starts a local server and opens your browser on the
+repository you named. Nothing is installed into the project, there is nothing
+to sign in to, and nothing leaves your machine.
+
+Comments persist between sessions and survive the code moving underneath them —
+including the agent's own edits, which shift every line below the first change —
+so a review you wrote yesterday still points at the right lines today. When you
+would rather read the review than pipe it, it also writes a plain Markdown file
+you can paste anywhere.
 
 ![The app reviewing a modified file: changed files on the left, a colour-coded diff in the middle with an inline comment and a threaded follow-up attached to line 10, and a comments sidebar on the right](docs/screenshot-comments.png)
 
@@ -109,8 +116,20 @@ shown in full, read back out of `HEAD`:
 
 ## What it writes
 
-Two files, both under `reviews/`, both plain text you can read without this
-app:
+Two files, both plain text you can read without this app, both in a per-user
+data directory outside the install:
+
+| platform | location |
+| --- | --- |
+| macOS | `~/Library/Application Support/git-reviewer` |
+| Linux, BSD | `$XDG_DATA_HOME/git-reviewer`, else `~/.local/share/git-reviewer` |
+| Windows | `%LOCALAPPDATA%\git-reviewer` |
+
+Set `REVIEWER_DATA_DIR` to put them anywhere else. They are deliberately *not*
+kept inside the installed package: that directory belongs to npm, which deletes
+it on upgrade and on uninstall, and `npx` puts it in a cache that is pruned
+without warning. A review you wrote by hand is the most expensive thing this
+tool holds.
 
 - **`.code-review-comments-<repo>.json`** — the live state of the review. It is
   written on every edit and is the source of truth; reopening the same
@@ -220,7 +239,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 163 tests
+npm test              # 206 tests
 npm run test:watch
 npm run test:coverage
 ```
@@ -268,7 +287,6 @@ including some tagged
 [good first issue](https://github.com/dheerajjha/reviewer/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 The ones most likely to change how the tool feels:
 
-- [#1](https://github.com/dheerajjha/reviewer/issues/1) — reviews are stored inside the install rather than with the repository
 - [#2](https://github.com/dheerajjha/reviewer/issues/2) — give comments a state, so a review can be worked through and marked off
 - [#3](https://github.com/dheerajjha/reviewer/issues/3) — report whether each anchor still matches the file
 - [#4](https://github.com/dheerajjha/reviewer/issues/4) — expose the review over MCP, so an agent works through it interactively

package/bin/reviewer.js

@@ -4,13 +4,17 @@
 const fs = require('fs').promises;
 const path = require('path');
 
-const simpleGit = require('simple-git');
-
 const { parseArgs, buildUrl, UsageError, USAGE } = require('../lib/cli');
 const { openInBrowser } = require('../lib/browser');
-const { buildReviewDocument, filterReviewDocument, formatPrompt } = require('../lib/agent');
-const { readSavedComments, ReviewOwnershipError } = require('../lib/store');
-const { startServer, DEFAULT_PORT, DEFAULT_HOST, REVIEWS_DIR } = require('../server');
+const { formatPrompt } = require('../lib/agent');
+const { ReviewOwnershipError } = require('../lib/store');
+const { reviewsDir, adoptLegacyReviews } = require('../lib/paths');
+const {
+  loadReviewDocument,
+  NoReviewError,
+  NoMatchingCommentsError
+} = require('../lib/export');
+const { startServer, DEFAULT_PORT, DEFAULT_HOST } = require('../server');
 const { version } = require('../package.json');
 
 /**
@@ -48,39 +52,23 @@ async function listen(port) {
 async function exportReview(options) {
   const repoPath = options.repoPath ?? process.cwd();
 
-  let comments;
+  let document;
   try {
-    ({ comments } = await readSavedComments(REVIEWS_DIR, repoPath));
+    document = await loadReviewDocument(reviewsDir(), repoPath, { file: options.file });
   } catch (error) {
-    if (error instanceof ReviewOwnershipError) throw new UsageError(error.message);
+    // `lib/export` raises domain errors so that an MCP tool or an agent
+    // handover can answer them its own way. The terminal wants all three as
+    // the same usage error, with the same wording it has always printed.
+    if (
+      error instanceof NoReviewError ||
+      error instanceof NoMatchingCommentsError ||
+      error instanceof ReviewOwnershipError
+    ) {
+      throw new UsageError(error.message);
+    }
     throw error;
   }
 
-  if (comments.length === 0) {
-    throw new UsageError(`No saved review for ${repoPath}. Review it first, then export.`);
-  }
-
-  // Recording the commit lets a consumer tell whether the tree has moved on
-  // since the review was written. Neither is fatal if git will not say.
-  const git = simpleGit(repoPath);
-  const head = await git.revparse(['HEAD']).then(sha => sha.trim()).catch(() => null);
-  const branch = await git.revparse(['--abbrev-ref', 'HEAD']).then(name => name.trim()).catch(() => null);
-
-  const document = filterReviewDocument(
-    buildReviewDocument({
-      repoPath,
-      comments,
-      generatedAt: new Date(),
-      head,
-      branch
-    }),
-    { file: options.file }
-  );
-
-  if (document.comments.length === 0) {
-    throw new UsageError(`The saved review for ${repoPath} has no comments for ${options.file}.`);
-  }
-
   process.stdout.write(
     options.format === 'prompt'
       ? formatPrompt(document)
@@ -91,6 +79,19 @@ async function exportReview(options) {
 async function main() {
   const options = parseArgs(process.argv.slice(2));
 
+  // Reviews written by a version that kept them inside the package directory
+  // are moved out before anything reads them. Once, synchronously, so no read
+  // can start against a half-populated directory. See #33.
+  const adopted = adoptLegacyReviews();
+  if (adopted > 0) {
+    console.log(
+      `  Copied ${adopted} saved review${adopted === 1 ? '' : 's'} out of the ` +
+        `install directory to\n  ${reviewsDir()}\n  so that upgrading or ` +
+        'reinstalling this package can no longer delete them.\n' +
+        '  The originals are left where they were.\n'
+    );
+  }
+
   if (options.help) {
     process.stdout.write(USAGE);
     return;

package/lib/agent.js

@@ -1,7 +1,8 @@
 'use strict';
 
+const path = require('path');
 const { groupByFile } = require('./comments');
-const { repoSlug } = require('./review');
+const { fence, repoSlug } = require('./review');
 
 /**
  * The machine-readable form of a review.
@@ -66,10 +67,43 @@ function buildReviewDocument({ repoPath, comments, generatedAt, head = null, bra
       comments: comments.length,
       files: grouped.length
     },
-    comments: grouped.flatMap(([, fileComments]) => fileComments.map(toAgentComment))
+    comments: assignIds(grouped.flatMap(([, fileComments]) => fileComments))
   };
 }
 
+/**
+ * Give every comment an id that is unique within the document.
+ *
+ * `<file>:<line>` was assumed to be unique because "the UI anchors one
+ * comment per line". It does not: in a diff, the removed line and the line
+ * that replaced it can carry the *same* number, one on each side, and
+ * commenting on both is two ordinary clicks. The export then contained two
+ * different comments under one id, and a consumer keyed by id — which is
+ * what an id is for — silently kept one of them. See #26.
+ *
+ * The first comment on a line keeps the bare `<file>:<line>`, so ids do not
+ * churn for the overwhelmingly common case and stay stable for anything
+ * already consuming them. Only a genuine collision gets a suffix.
+ *
+ * Stable across exports because the order is: `groupByFile` sorts by line
+ * with a stable sort, so two comments sharing a line keep the order they
+ * were saved in, and saving appends.
+ *
+ * @param {import('./comments').Comment[]} comments in document order
+ * @returns {AgentComment[]}
+ */
+function assignIds(comments) {
+  const seen = new Map();
+
+  return comments.map(comment => {
+    const base = `${comment.file}:${comment.line}`;
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return toAgentComment(comment, n === 1 ? base : `${base}#${n}`);
+  });
+}
+
+
 /**
  * Select comments from an already-built document and keep its summary honest.
  *
@@ -81,7 +115,8 @@ function buildReviewDocument({ repoPath, comments, generatedAt, head = null, bra
 function filterReviewDocument(document, { file = null } = {}) {
   if (file === null) return document;
 
-  const comments = document.comments.filter(comment => comment.file === file);
+  const wanted = normalizeReviewPath(file, document.repository.path);
+  const comments = document.comments.filter(comment => comment.file === wanted);
   return {
     ...document,
     summary: {
@@ -92,15 +127,36 @@ function filterReviewDocument(document, { file = null } = {}) {
   };
 }
 
+/**
+ * Turn a `--file` argument into the repo-relative, forward-slash form comments
+ * are stored in.
+ *
+ * Shells hand paths over as `./src/auth.js` on tab-completion, scripts often
+ * pass absolute paths, and Windows users type backslashes. Matching literally
+ * made every one of those miss and fail with the same error as a file that
+ * genuinely has no comments.
+ *
+ * @param {string} file
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function normalizeReviewPath(file, repoPath) {
+  let candidate = file;
+  if (path.isAbsolute(candidate)) candidate = path.relative(repoPath, candidate);
+
+  const normalized = path.posix.normalize(candidate.replace(/\\/g, '/'));
+  return normalized.replace(/^(\.\/)+/, '').replace(/\/$/, '');
+}
+
 /**
  * @param {import('./comments').Comment} comment
  * @returns {AgentComment}
  */
-function toAgentComment(comment) {
+function toAgentComment(comment, id) {
   const entry = {
-    // File and line identify a comment uniquely — the UI anchors one comment
-    // per line — and staying derived keeps ids stable across exports.
-    id: `${comment.file}:${comment.line}`,
+    // Derived from file and line so it stays stable across exports, with a
+    // suffix where that is not enough on its own. See `assignIds`.
+    id,
     file: comment.file,
     line: comment.line,
     anchor: comment.lineContent ?? null,
@@ -158,11 +214,16 @@ function formatPrompt(document) {
     }
 
     lines.push(`### ${comment.id}`, '');
+    // Fenced with `fence`, not a literal ```, because the anchor is arbitrary
+    // source and in a Markdown file it is routinely a fence itself. A
+    // same-length marker closes the block on the anchor's own line, and the
+    // comment body below it — the instruction the agent is meant to act on —
+    // becomes code, taking the next comment's heading with it. See #22.
     if (comment.anchor !== null) {
-      lines.push('Anchor line:', '', '```', comment.anchor, '```', '');
+      lines.push('Anchor line:', '', fence(comment.anchor), '');
     }
     if (comment.selection) {
-      lines.push('Selected code:', '', '```', comment.selection, '```', '');
+      lines.push('Selected code:', '', fence(comment.selection), '');
     }
 
     lines.push(comment.body, '');

package/lib/export.js

@@ -0,0 +1,205 @@
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+
+const simpleGit = require('simple-git');
+
+const { buildReviewDocument, filterReviewDocument } = require('./agent');
+const { readSavedComments, belongsTo } = require('./store');
+const { commentsFilename, canonicalRepoPath, repoSlug } = require('./review');
+
+/**
+ * Producing a `code-review/v1` document from a repository on disk.
+ *
+ * This chain — read the saved comments, build the document, filter it — used
+ * to be assembled exactly once, inside a local un-exported function in
+ * `bin/reviewer.js`. That was fine while the CLI was the only consumer. It
+ * stops being fine the moment there is a second one, because the second
+ * consumer cannot call it and has to rebuild it, and then the two copies
+ * drift in the way that matters most: quietly, and only in the edge cases.
+ *
+ * The HTTP server reaches the same document by a third route entirely
+ * (`POST /api/submit-review`), which is session-bound and writes two files to
+ * disk as a side effect of being asked for a document. That one is left alone
+ * here; this module is what anything new should call.
+ *
+ * Nothing in here knows about the CLI. The three conditions the CLI reports
+ * as usage errors are raised as domain errors and translated at the boundary,
+ * so an MCP tool or an agent handover can answer them its own way rather than
+ * inheriting a message written for a terminal.
+ */
+
+/** No review has been saved for this repository. */
+class NoReviewError extends Error {
+  /** @param {string} repoPath */
+  constructor(repoPath) {
+    super(`No saved review for ${repoPath}. Review it first, then export.`);
+    this.name = 'NoReviewError';
+    this.repoPath = repoPath;
+  }
+}
+
+/** A review exists, but the requested filter selected none of it. */
+class NoMatchingCommentsError extends Error {
+  /**
+   * @param {string} repoPath
+   * @param {string} file the filter that matched nothing
+   */
+  constructor(repoPath, file) {
+    super(`The saved review for ${repoPath} has no comments for ${file}.`);
+    this.name = 'NoMatchingCommentsError';
+    this.repoPath = repoPath;
+    this.file = file;
+  }
+}
+
+/**
+ * Where the working tree is, as far as git will say.
+ *
+ * Every failure here is answered with nulls rather than raised. A review is
+ * still a review when git cannot be reached, and this has to hold for three
+ * separate failures that do not look alike:
+ *
+ *   - the directory is not a repository       -> revparse rejects
+ *   - git is not installed                    -> revparse rejects
+ *   - the directory does not exist at all     -> `simpleGit()` throws
+ *     *synchronously, at construction*, which is why the constructor is
+ *     inside the try and not above it. The CLI never hit this because
+ *     `main()` does an `fs.access` check first; a library has no such
+ *     guarantee, and an agent asking about a repository that has since been
+ *     moved or deleted would otherwise get a crash instead of an answer.
+ *
+ * @param {string} repoPath
+ * @returns {Promise<{head: string|null, branch: string|null}>}
+ */
+async function readGitPosition(repoPath) {
+  try {
+    const git = simpleGit(repoPath);
+    const [head, branch] = await Promise.all([
+      git.revparse(['HEAD']).then(sha => sha.trim()).catch(() => null),
+      git.revparse(['--abbrev-ref', 'HEAD']).then(name => name.trim()).catch(() => null)
+    ]);
+    return { head, branch };
+  } catch {
+    return { head: null, branch: null };
+  }
+}
+
+/**
+ * Load a repository's saved review as a `code-review/v1` document.
+ *
+ * @param {string} reviewsDir directory holding the saved comment files
+ * @param {string} repoPath repository to export
+ * @param {object} [options]
+ * @param {string|null} [options.file] restrict to one repo-relative path
+ * @returns {Promise<import('./agent').ReviewDocument>}
+ * @throws {NoReviewError} when nothing has been saved for this repository
+ * @throws {NoMatchingCommentsError} when `file` selects no comments
+ * @throws {import('./store').ReviewOwnershipError} when the file on disk
+ *   records a different repository than the one asked for
+ */
+async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
+  const { comments } = await readSavedComments(reviewsDir, repoPath);
+
+  if (comments.length === 0) throw new NoReviewError(repoPath);
+
+  // Recording the commit lets a consumer tell whether the tree has moved on
+  // since the review was written. Neither is fatal if git will not say.
+  //
+  // Caveat worth knowing before you build on this: `head` is read live, here,
+  // at export time -- it is not what HEAD was when the review was written. So
+  // docs/agent-format.md telling consumers to compare it against current HEAD
+  // to detect staleness cannot work, because it is always current HEAD. That
+  // is a real contract bug (#32); it is reproduced rather than fixed here so
+  // this stays the pure lift it claims to be, and so the fix lands where it
+  // can change the stored format deliberately.
+  const { head, branch } = await readGitPosition(repoPath);
+
+  // Build then filter, in that order, and do not tidy this into one step:
+  // `filterReviewDocument` recomputes `summary` honestly and returns the very
+  // 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 }),
+    { file }
+  );
+
+  if (document.comments.length === 0) throw new NoMatchingCommentsError(repoPath, file);
+
+  return document;
+}
+
+/**
+ * Every repository with a saved review in `reviewsDir`.
+ *
+ * Nothing in this codebase enumerated `reviews/` before: there was no way to
+ * ask "which repositories have reviews?", only to ask about one you already
+ * knew the path of. Any agent-facing surface needs discovery first.
+ *
+ * Entries are reported from what each file records about itself, with the
+ * same ownership rule `readSavedComments` enforces: a file whose recorded
+ * repository disagrees with its own filename is corrupt and is skipped rather
+ * than listed under a name it does not own. Unreadable and unparseable files
+ * are skipped for the same reason — a listing that throws because one file in
+ * the directory is damaged is useless.
+ *
+ * A missing `reviewsDir` is an empty list, not an error: nobody has reviewed
+ * anything yet.
+ *
+ * @param {string} reviewsDir
+ * @returns {Promise<Array<{repoPath: string, name: string, comments: number, updatedAt: string}>>}
+ *   newest first
+ */
+async function listReviews(reviewsDir) {
+  let names;
+  try {
+    names = await fs.readdir(reviewsDir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const reviews = [];
+
+  for (const name of names) {
+    if (!name.startsWith('.code-review-comments-') || !name.endsWith('.json')) continue;
+
+    const file = path.join(reviewsDir, name);
+
+    let saved;
+    let stat;
+    try {
+      [saved, stat] = await Promise.all([
+        fs.readFile(file, 'utf-8').then(JSON.parse),
+        fs.stat(file)
+      ]);
+    } catch {
+      continue; // unreadable or not JSON; a damaged file is not a listing failure
+    }
+
+    const repoPath = saved?.repoPath;
+    if (typeof repoPath !== 'string' || repoPath === '') continue;
+
+    // The filename carries a fingerprint of the canonical path. If the file
+    // records a repository that would not produce this filename, the two
+    // disagree about who it belongs to, and store.js would refuse to serve
+    // it. Listing it anyway would advertise a review that cannot be opened.
+    if (commentsFilename(repoPath) !== name) continue;
+    if (!belongsTo(repoPath, repoPath)) continue;
+
+    const comments = Array.isArray(saved.comments) ? saved.comments.length : 0;
+    if (comments === 0) continue; // an emptied review is not a review
+
+    reviews.push({
+      repoPath: canonicalRepoPath(repoPath),
+      name: repoSlug(repoPath),
+      comments,
+      updatedAt: stat.mtime.toISOString()
+    });
+  }
+
+  return reviews.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+module.exports = { loadReviewDocument, listReviews, NoReviewError, NoMatchingCommentsError };

package/lib/paths.js

@@ -1,11 +1,117 @@
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 /**
- * Confining request-supplied paths to the repository being reviewed.
+ * Where review state lives, and confining request-supplied paths to the
+ * repository being reviewed.
  */
 
+/** The directory reviews were written to before #33. Inside the package. */
+const LEGACY_REVIEWS_DIR = path.join(__dirname, '..', 'reviews');
+
+/**
+ * The per-user directory this tool may keep state in.
+ *
+ * Reviews used to be written to `<package>/reviews`, which put user data
+ * inside a directory npm owns and reuses. Both of the things npm does to that
+ * directory destroy the data:
+ *
+ *   npm uninstall git-reviewer     -> the reviews go with it
+ *   npm i git-reviewer@<newer>     -> npm replaces the package directory
+ *
+ * and `npx git-reviewer .` -- the command the README leads with -- writes into
+ * the npx cache, which is pruned on npm's schedule rather than the user's.
+ *
+ * A review someone wrote by hand is the most expensive thing this tool holds.
+ * It does not belong anywhere a package manager is entitled to delete.
+ *
+ * @returns {string}
+ */
+function userDataDir() {
+  const home = os.homedir();
+
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support');
+  }
+
+  if (process.platform === 'win32') {
+    return (
+      process.env.LOCALAPPDATA ||
+      process.env.APPDATA ||
+      path.join(home, 'AppData', 'Local')
+    );
+  }
+
+  return process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+}
+
+/**
+ * Where comment state and submitted reviews are written.
+ *
+ * Resolved on every call rather than frozen at import, so that setting
+ * `REVIEWER_DATA_DIR` always takes effect. That is not only a convenience:
+ * the test suite spawns the real CLI, and a value captured at import time
+ * would have those tests writing into the developer's actual review
+ * directory.
+ *
+ * @returns {string}
+ */
+function reviewsDir() {
+  const override = process.env.REVIEWER_DATA_DIR;
+  if (override) return path.resolve(override);
+  return path.join(userDataDir(), 'git-reviewer');
+}
+
+/**
+ * Move reviews written by an older version out of the package directory.
+ *
+ * Same shape, and the same reasoning, as the legacy-filename adoption in
+ * `lib/store.js`: a review someone wrote is not ours to abandon because we
+ * changed our minds about where it belongs.
+ *
+ * Copy rather than rename: the source may be read-only, on another device, or
+ * an npx cache we do not own, and none of those is a reason to fail. Existing
+ * files at the destination always win -- a second run must not overwrite newer
+ * work with the stale copy it already migrated.
+ *
+ * Synchronous on purpose. It runs once, before anything can read the
+ * directory, and an async version would let a read start against a directory
+ * that is still half-populated.
+ *
+ * @param {string} [target] defaults to the resolved reviews directory
+ * @returns {number} how many files were adopted
+ */
+function adoptLegacyReviews(target = reviewsDir()) {
+  if (path.resolve(target) === path.resolve(LEGACY_REVIEWS_DIR)) return 0;
+
+  let names;
+  try {
+    names = fs.readdirSync(LEGACY_REVIEWS_DIR);
+  } catch {
+    return 0; // nothing written by an older version
+  }
+
+  let adopted = 0;
+  for (const name of names) {
+    const from = path.join(LEGACY_REVIEWS_DIR, name);
+    const to = path.join(target, name);
+    try {
+      if (!fs.statSync(from).isFile()) continue;
+      if (fs.existsSync(to)) continue;
+      fs.mkdirSync(target, { recursive: true });
+      fs.copyFileSync(from, to);
+      adopted += 1;
+    } catch {
+      /* one unreadable file is not a reason to abandon the rest */
+    }
+  }
+
+  return adopted;
+}
+
 class PathEscapeError extends Error {
   /** @param {string} requested the offending path, as received */
   constructor(requested) {
@@ -49,4 +155,19 @@ function resolveRepoFile(repoPath, filePath) {
   return resolved;
 }
 
-module.exports = { resolveRepoFile, PathEscapeError };
+module.exports = {
+  reviewsDir,
+  userDataDir,
+  adoptLegacyReviews,
+  LEGACY_REVIEWS_DIR,
+  resolveRepoFile,
+  PathEscapeError
+};
+
+// Kept so `require('./lib/paths').REVIEWS_DIR` and the server's re-export
+// keep working. A getter, not a value, so it honours REVIEWER_DATA_DIR at
+// the moment it is read.
+Object.defineProperty(module.exports, 'REVIEWS_DIR', {
+  get: reviewsDir,
+  enumerable: true
+});

package/lib/review.js

@@ -179,6 +179,8 @@ function formatComment(comment) {
  * @param {string} text
  * @returns {string}
  */
+// Exported for lib/agent.js: the prompt format has the same problem this
+// solves, and one rule for choosing a marker is better than two.
 function fence(text) {
   const longest = String(text).match(/^`{3,}/gm)?.reduce((a, b) => (b.length > a.length ? b : a), '') ?? '';
   const marker = '`'.repeat(Math.max(3, longest.length + 1));
@@ -197,6 +199,7 @@ function formatTimestamp(timestamp) {
 
 module.exports = {
   formatReview,
+  fence,
   reviewFilename,
   commentsFilename,
   legacyCommentsFilename,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "git-reviewer",
-  "version": "2.0.0",
-  "description": "Review local git changes in your browser with inline comments and threaded follow-ups \u2014 no branch, remote, or account required",
+  "version": "2.2.0",
+  "description": "Review your coding agent's changes like a pull request \u2014 locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",
   "homepage": "https://github.com/dheerajjha/reviewer#readme",
@@ -14,11 +14,17 @@
   },
   "keywords": [
     "code-review",
+    "code-review-tool",
     "git",
     "diff",
     "review",
     "cli",
-    "developer-tools"
+    "developer-tools",
+    "ai",
+    "agent",
+    "coding-agent",
+    "llm",
+    "local-first"
   ],
   "engines": {
     "node": ">=18.0.0"

package/public/app.js

@@ -296,7 +296,7 @@ async function loadFile(filePath, index) {
       updateCommentsSidebar();
     }
 
-    displayCode(data.filePath, data.diffLines);
+    displayCode(data.filePath, data.diffLines, data.binary);
     updateFullContextButton();
     return Promise.resolve();
 
@@ -307,7 +307,7 @@ async function loadFile(filePath, index) {
 }
 
 // Display code with diff highlighting
-function displayCode(filePath, diffLines) {
+function displayCode(filePath, diffLines, binary) {
   const codeSection = document.getElementById('codeSection');
   const currentFileEl = document.getElementById('currentFile');
   const codeViewer = document.getElementById('codeViewer');
@@ -315,6 +315,19 @@ function displayCode(filePath, diffLines) {
   currentFileEl.textContent = filePath;
   currentDiffLines = diffLines; // Store for reference when adding comments
 
+  // A binary file has no lines to show and none to comment on. Saying so is
+  // the whole feature: it used to be decoded as UTF-8 and rendered as
+  // mojibake, and a comment left on one of those lines exported an anchor
+  // that could never match the file again.
+  if (binary) {
+    codeSection.style.display = 'block';
+    codeViewer.innerHTML =
+      '<div class="binary-notice">Binary file &mdash; not shown.' +
+      '<span>git reports this file as binary, so there are no lines to ' +
+      'review. Comments need a line to anchor to.</span></div>';
+    return;
+  }
+
   const fileComments = comments.filter(c => c.file === filePath);
 
   let html = '';

package/public/style.css

@@ -988,3 +988,19 @@ button:disabled {
   color: #24292e;
   border: 1px solid #e1e4e8;
 }
+
+/* A binary file has no lines to render; say so rather than showing a
+   lossy UTF-8 decode of its bytes. See #23. */
+.binary-notice {
+  padding: 28px 24px;
+  color: #57606a;
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.binary-notice span {
+  display: block;
+  margin-top: 6px;
+  font-size: 13px;
+  opacity: 0.8;
+}

package/server.js

@@ -7,7 +7,11 @@ const fs = require('fs').promises;
 const path = require('path');
 
 const { parseDiff } = require('./lib/diff');
-const { resolveRepoFile, PathEscapeError } = require('./lib/paths');
+const {
+  reviewsDir: resolveReviewsDir,
+  resolveRepoFile,
+  PathEscapeError
+} = require('./lib/paths');
 const { collectWorkingChanges, collectCommitChanges } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
 const { normalizeComments } = require('./lib/comments');
@@ -18,8 +22,6 @@ const { readSavedComments, ReviewOwnershipError } = require('./lib/store');
 const DEFAULT_PORT = 4500;
 const DEFAULT_HOST = '127.0.0.1';
 
-/** Where comment state and submitted reviews are written. */
-const REVIEWS_DIR = path.join(__dirname, 'reviews');
 
 /** A path inside the repository that names nothing, on disk or at HEAD. */
 class FileNotFoundError extends Error {
@@ -46,7 +48,7 @@ class FileNotFoundError extends Error {
  */
 function createApp(options = {}) {
   const {
-    reviewsDir = REVIEWS_DIR,
+    reviewsDir = resolveReviewsDir(),
     sessions = new SessionStore(),
     git: gitFactory = simpleGit
   } = options;
@@ -147,6 +149,29 @@ function createApp(options = {}) {
    * @param {string} filePath
    * @returns {Promise<string>}
    */
+  /**
+   * Whether git considers this file binary.
+   *
+   * Asking git rather than sniffing the bytes ourselves, because git's
+   * answer is the one that produced the diff we are about to render, and a
+   * second opinion that disagreed would be worse than no opinion. It says
+   * so in the diff itself: `Binary files a/x and b/x differ` for the
+   * default format, `GIT binary patch` when binary patches are enabled.
+   *
+   * This matters beyond the mojibake. `lib/changes.js` already classifies
+   * these as `B` and the sidebar renders that letter, but the file endpoint
+   * never consulted it -- so a 2 KB PNG came back as ten `add` lines that
+   * were ~45% U+FFFD, and a comment left on one of them exported an
+   * `anchor` that can never match the file. docs/agent-format.md tells a
+   * consumer to locate comments by that anchor.
+   *
+   * @param {string} diffText
+   * @returns {boolean}
+   */
+  function isBinaryDiff(diffText) {
+    return /^Binary files .* differ$/m.test(diffText) || /^GIT binary patch$/m.test(diffText);
+  }
+
   async function diffForFile(git, session, filePath) {
     if (session.mode === 'lastCommit') {
       return git.diff(['HEAD~1', 'HEAD', '--', filePath]);
@@ -219,11 +244,26 @@ function createApp(options = {}) {
       const session = requireSession(res, repoId);
       if (!session) return;
 
+      // Confine the path first, explicitly. It used to be confined as a
+      // side effect of `readFileForMode` calling `resolveRepoFile`, so
+      // moving the read below the binary check silently turned a 400 into a
+      // 500 and let the traversal reach git. A containment check that only
+      // works because of statement order is not a containment check.
+      resolveRepoFile(session.repoPath, filePath);
+
       const git = gitFactory(session.repoPath);
-      const content = await readFileForMode(session, filePath);
       const diffText = await diffForFile(git, session, filePath);
 
-      res.json({ filePath, diffLines: parseDiff(diffText, content) });
+      // Answered before the file is read: decoding a PNG as UTF-8 to then
+      // throw the result away is how the mojibake got served in the first
+      // place.
+      if (isBinaryDiff(diffText)) {
+        return res.json({ filePath, binary: true, diffLines: [] });
+      }
+
+      const content = await readFileForMode(session, filePath);
+
+      res.json({ filePath, binary: false, diffLines: parseDiff(diffText, content) });
     } catch (error) {
       if (error instanceof PathEscapeError) {
         return res.status(400).json({ error: error.message });
@@ -418,4 +458,11 @@ if (require.main === module) {
   });
 }
 
-module.exports = { createApp, startServer, DEFAULT_PORT, DEFAULT_HOST, REVIEWS_DIR };
+module.exports = { createApp, startServer, DEFAULT_PORT, DEFAULT_HOST };
+
+// Re-exported as a getter so existing callers keep working and still see
+// REVIEWER_DATA_DIR. See lib/paths.js.
+Object.defineProperty(module.exports, 'REVIEWS_DIR', {
+  get: resolveReviewsDir,
+  enumerable: true
+});