git-reviewer 2.2.0 → 2.3.0

package/README.md

@@ -3,11 +3,9 @@
 [![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-206-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-261-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)
-
 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.
@@ -18,13 +16,21 @@ 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
-npx git-reviewer .                       # read the diff, leave comments
-npx git-reviewer export . --format prompt | claude -p "Apply this review."
+npm install -g git-reviewer
+
+cd ~/your-project
+reviewer                                            # read the diff, comment on it
+reviewer export . --format prompt | claude -p "Apply this review."
 ```
 
-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.
+![A terminal installing git-reviewer and running it inside a project; the browser opens on the diff with the first changed file already showing; two review comments are written inline, one with a threaded follow-up; then reviewer export prints those same comments back for a coding agent to act on](docs/demo.gif)
+
+*The whole loop, unedited and in real time — [full resolution](docs/demo.mp4).*
+
+`reviewer` starts a local server and opens your browser on the repository you
+are standing in. Nothing is installed into the project, there is nothing to
+sign in to, and nothing leaves your machine. If you would rather not install
+it, `npx git-reviewer` works the same way.
 
 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 —
@@ -43,7 +49,8 @@ comment they answer, and everything is saved as you type.
 reviewer [repository] [options]
 reviewer export [repository] [--format json|prompt]
 
-  repository        Path to a git repository (default: the current directory)
+  repository        A git repository, or any directory inside one
+                    (default: the current directory)
 
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
@@ -62,6 +69,25 @@ reviewer . --port 8080      # somewhere other than 4500
 
 Two at once is fine — the second one finds its own port.
 
+### When you are not standing in a repository
+
+The page opens on a picker rather than on an empty box:
+
+- **Recent** — repositories you have opened before, newest first, with how many
+  comments are saved against each. One click reopens one.
+- **Browse** — walk the filesystem from your home directory. Repositories are
+  marked, so you can see where to stop; a folder row walks into it, and the
+  button beside a marked one opens it.
+
+Only directory names are listed, never file names, and the two endpoints behind
+this refuse a request a browser says came from another origin.
+
+The header leads with the repository you have open; click it to switch. Beside
+it is a small keyboard icon that reveals a path box, for when the path is
+already on your clipboard and a navigator is the slow way round.
+
+![The picker: a Recent list of previously opened repositories, each showing where it lives and how many comments are saved against it, above a Browse list walking the filesystem with git repositories marked](docs/screenshot-picker.png)
+
 To install it as a command rather than running it through `npx`:
 
 ```bash
@@ -70,8 +96,14 @@ reviewer .
 ```
 
 The package is `git-reviewer` because `reviewer` and `code-reviewer` were both
-already taken on npm. The command it installs is still `reviewer` -- the
-package name is a distribution detail, the command is the product.
+already taken on npm. It installs the command under both names, so whichever
+one you reach for is the one that is there:
+
+```bash
+reviewer                    # the command
+git-reviewer                # the package name, if that is what you typed
+git reviewer                # git dispatches to it like any other subcommand
+```
 
 From a clone, if you would rather not install anything:
 
@@ -239,7 +271,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 206 tests
+npm test              # 261 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -9,6 +9,7 @@ const { openInBrowser } = require('../lib/browser');
 const { formatPrompt } = require('../lib/agent');
 const { ReviewOwnershipError } = require('../lib/store');
 const { reviewsDir, adoptLegacyReviews } = require('../lib/paths');
+const { repoRoot } = require('../lib/repo');
 const {
   loadReviewDocument,
   NoReviewError,
@@ -50,7 +51,13 @@ async function listen(port) {
  * @param {import('../lib/cli').CliOptions} options
  */
 async function exportReview(options) {
-  const repoPath = options.repoPath ?? process.cwd();
+  // Saved reviews are filed under the repository root, so exporting from a
+  // subdirectory has to look there too — otherwise the browser saves a review
+  // one directory up and this reports that none exists. Falling back to the
+  // path as given keeps the case `lib/export.js` deliberately supports: a
+  // review whose repository is no longer a repository is still exportable.
+  const given = options.repoPath ?? process.cwd();
+  const repoPath = (await repoRoot(given)) ?? given;
 
   let document;
   try {
@@ -76,6 +83,27 @@ async function exportReview(options) {
   );
 }
 
+/**
+ * Which repository the page should open.
+ *
+ * `reviewer` with no argument reviews the repository you are standing in.
+ * `--help` has promised that since the first release and the code never did
+ * it, so the page opened on an empty path box instead.
+ *
+ * Naming a directory and defaulting to one are answered differently on
+ * purpose. Name one, and you are told when it is not a repository, because
+ * you asked about it. Nobody asked for the current directory in particular —
+ * so when that is not inside a repository the page opens on its picker
+ * exactly as it always has, rather than greeting you with an error.
+ *
+ * @param {string|null} given the repository named on the command line
+ * @returns {Promise<string|null>} repository to open, or null for the picker
+ */
+async function repositoryToOpen(given) {
+  if (given) return (await repoRoot(given)) ?? given;
+  return repoRoot(process.cwd());
+}
+
 async function main() {
   const options = parseArgs(process.argv.slice(2));
 
@@ -114,11 +142,13 @@ async function main() {
     return exportReview(options);
   }
 
+  const repoPath = await repositoryToOpen(options.repoPath);
+
   const server = await listen(options.port ?? (Number(process.env.PORT) || DEFAULT_PORT));
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, options.repoPath);
+  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
 
   console.log(`\n  Code Reviewer  ${url}`);
-  if (options.repoPath) console.log(`  reviewing      ${options.repoPath}`);
+  if (repoPath) console.log(`  reviewing      ${repoPath}`);
   console.log('\n  Press Ctrl+C to stop.\n');
 
   if (options.open && !(await openInBrowser(url))) {

package/lib/browse.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const fs = require('fs').promises;
+const os = require('os');
+const path = require('path');
+
+const { homeRelative } = require('./paths');
+
+/**
+ * Listing directories, so a repository can be found by looking rather than by
+ * being typed from memory.
+ *
+ * Only directories are reported. A picker picks a folder, so file names are
+ * not the question — and not answering it keeps this from being a way to read
+ * the shape of someone's disk when all it needs to do is navigate.
+ */
+
+/**
+ * Directories that are never worth offering.
+ *
+ * `.git` is a repository's own plumbing: listing it invites clicking into it,
+ * and what is inside is not reviewable. `node_modules` is thousands of
+ * directories nobody is looking for.
+ */
+const NEVER_LIST = new Set(['.git', 'node_modules']);
+
+/**
+ * Is this directory the root of a working tree?
+ *
+ * Decided by the presence of `.git` rather than by asking git, because this
+ * runs once per row and a subprocess per row would make a home directory take
+ * seconds to list. `.git` is a directory in an ordinary clone and a *file* in
+ * a worktree or a submodule, so existence is the question and type is not.
+ *
+ * This is a hint for the UI. `lib/repo.js` stays the authority on what gets
+ * opened, so a wrong guess here costs a click, not a wrong review.
+ *
+ * @param {string} dir
+ * @returns {Promise<boolean>}
+ */
+async function isRepository(dir) {
+  try {
+    await fs.stat(path.join(dir, '.git'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve one directory entry, following symlinks.
+ *
+ * `withFileTypes` reports a symlink as a symlink, not as what it points at,
+ * and a home directory with `~/code -> /Volumes/work/code` in it is ordinary.
+ * Following it costs a stat; not following it hides the projects.
+ *
+ * @param {string} parent
+ * @param {import('fs').Dirent} entry
+ * @returns {Promise<{name: string, path: string, isRepository: boolean}|null>}
+ *   null when the entry is not a directory, or cannot be read at all
+ */
+async function describe(parent, entry) {
+  if (NEVER_LIST.has(entry.name)) return null;
+
+  const full = path.join(parent, entry.name);
+
+  if (!entry.isDirectory()) {
+    if (!entry.isSymbolicLink()) return null;
+    try {
+      if (!(await fs.stat(full)).isDirectory()) return null;
+    } catch {
+      return null; // dangling symlink
+    }
+  }
+
+  const repository = await isRepository(full);
+
+  // Hidden directories are noise in a home directory -- `.cache`, `.npm`,
+  // `.Trash` -- but `~/.dotfiles` is one of the most commonly reviewed
+  // repositories there is. Hide the hidden ones, except the ones that are
+  // repositories, which is the only reason to be looking in here.
+  if (entry.name.startsWith('.') && !repository) return null;
+
+  return { name: entry.name, path: full, isRepository: repository };
+}
+
+/**
+ * List the directories inside `target`.
+ *
+ * An entry that cannot be read is skipped rather than failing the listing: one
+ * unreadable directory in a home folder should not make the folder unbrowsable.
+ *
+ * @param {string} [target] directory to list; the home directory by default
+ * @returns {Promise<{path: string, display: string, parent: string|null,
+ *   isRepository: boolean,
+ *   entries: Array<{name: string, path: string, isRepository: boolean}>}>}
+ * @throws an fs error with `code` ENOENT, ENOTDIR or EACCES for the caller to map
+ */
+async function browse(target) {
+  const asked = typeof target === 'string' ? target.trim() : '';
+  const dir = path.resolve(asked === '' ? os.homedir() : asked);
+
+  const stats = await fs.stat(dir);
+  if (!stats.isDirectory()) {
+    throw Object.assign(new Error(`Not a directory: ${dir}`), { code: 'ENOTDIR' });
+  }
+
+  const described = await Promise.all(
+    (await fs.readdir(dir, { withFileTypes: true })).map(entry => describe(dir, entry))
+  );
+
+  const parent = path.dirname(dir);
+
+  return {
+    path: dir,
+    // The same directory, written the way a person writes it. `path` stays
+    // absolute because that is what gets opened; this is what gets read.
+    display: homeRelative(dir),
+    // At the filesystem root, dirname answers with the root again. There is
+    // nowhere further up, and a parent row that goes nowhere is a bug report.
+    parent: parent === dir ? null : parent,
+    isRepository: await isRepository(dir),
+    entries: described
+      .filter(Boolean)
+      .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }))
+  };
+}
+
+module.exports = { browse, isRepository, NEVER_LIST };

package/lib/cli.js

@@ -15,9 +15,13 @@ Usage:
   reviewer [repository] [options]
   reviewer export [repository] [--format json|prompt] [--file <path>]
 
+Installed under both names: reviewer and git-reviewer. The second name also
+makes it reachable as a git subcommand: git reviewer
+
 Arguments:
-  repository        Path to a git repository. Defaults to the current
-                    directory. It is opened automatically once the page loads.
+  repository        Path to a git repository, or to any directory inside one.
+                    Defaults to the current directory. It is opened
+                    automatically once the page loads.
 
 Commands:
   export            Print the saved review of a repository to stdout, for a
@@ -228,7 +232,17 @@ function parseFile(value, flag) {
  */
 function buildUrl(origin, repoPath) {
   if (!repoPath) return origin;
-  return `${origin}/?repo=${encodeURIComponent(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.
+  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`;
 }
 
 module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS };

package/lib/paths.js

@@ -155,12 +155,37 @@ function resolveRepoFile(repoPath, filePath) {
   return resolved;
 }
 
+/**
+ * A path as a person would write it, with the home directory as `~`.
+ *
+ * For display only — nothing resolves a `~` back, and nothing should. An
+ * absolute path is the right thing to store, to compare and to hand to git;
+ * it is the wrong thing to put in a list of projects, where the first forty
+ * characters are the same on every row and the part that identifies the row
+ * is the part that gets cut off.
+ *
+ * @param {string} target
+ * @param {string} [home]
+ * @returns {string}
+ */
+function homeRelative(target, home = os.homedir()) {
+  const resolved = path.resolve(String(target ?? ''));
+
+  if (resolved === home) return '~';
+  if (home && resolved.startsWith(home + path.sep)) {
+    return `~${resolved.slice(home.length)}`;
+  }
+
+  return resolved;
+}
+
 module.exports = {
   reviewsDir,
   userDataDir,
   adoptLegacyReviews,
   LEGACY_REVIEWS_DIR,
   resolveRepoFile,
+  homeRelative,
   PathEscapeError
 };
 

package/lib/recents.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('fs').promises;
+const pathModule = require('path');
+
+const { canonicalRepoPath, repoSlug } = require('./review');
+const { homeRelative } = require('./paths');
+
+/**
+ * The repositories this machine has opened, newest first.
+ *
+ * `listReviews` already answers a related question — which repositories have a
+ * saved review — but that is not the same list. A repository you opened,
+ * read and left without commenting on has no review and is exactly the one you
+ * want offered back to you next time.
+ */
+
+/** Filename inside the data directory. Not a review, so `listReviews` skips it. */
+const RECENTS_FILE = 'recent-projects.json';
+
+/** How many to keep. Long enough to cover what you are working on, short enough to read. */
+const LIMIT = 10;
+
+/**
+ * @param {string} dataDir
+ * @returns {string}
+ */
+function recentsFile(dataDir) {
+  return pathModule.join(dataDir, RECENTS_FILE);
+}
+
+/**
+ * Read the recorded list.
+ *
+ * Answers an empty list for every failure — absent, unreadable, not JSON, or
+ * JSON of the wrong shape. A damaged recents file is a lost convenience, and
+ * it must not be allowed to become a failure to open a repository.
+ *
+ * @param {string} dataDir
+ * @returns {Promise<Array<{path: string, openedAt: string}>>} newest first
+ */
+async function readRecents(dataDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(recentsFile(dataDir), 'utf-8'));
+  } catch {
+    return [];
+  }
+
+  if (!Array.isArray(parsed?.projects)) return [];
+
+  return parsed.projects.filter(
+    project =>
+      typeof project?.path === 'string' &&
+      project.path !== '' &&
+      typeof project.openedAt === 'string'
+  );
+}
+
+/**
+ * Record a repository as just opened.
+ *
+ * Written to a temporary file and renamed, so two `reviewer` processes racing
+ * cannot leave a half-written list behind. The loser of the race loses one
+ * entry, which is the right thing to lose.
+ *
+ * @param {string} dataDir
+ * @param {string} repoPath
+ * @param {Date} [now]
+ * @returns {Promise<Array<{path: string, openedAt: string}>>} the new list
+ */
+async function recordRecent(dataDir, repoPath, now = new Date()) {
+  const canonical = canonicalRepoPath(repoPath);
+  const existing = await readRecents(dataDir);
+
+  const projects = [
+    { path: canonical, openedAt: now.toISOString() },
+    ...existing.filter(project => canonicalRepoPath(project.path) !== canonical)
+  ].slice(0, LIMIT);
+
+  await fs.mkdir(dataDir, { recursive: true });
+
+  const temporary = `${recentsFile(dataDir)}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, `${JSON.stringify({ version: 1, projects }, null, 2)}\n`);
+  await fs.rename(temporary, recentsFile(dataDir));
+
+  return projects;
+}
+
+/**
+ * The recent list, as the picker needs to draw it.
+ *
+ * A repository that has been moved or deleted is reported rather than dropped:
+ * seeing it greyed out with the path you remember is a better answer than a
+ * list that quietly gets shorter.
+ *
+ * @param {string} dataDir
+ * @param {Map<string, number>} [commentCounts] repository path -> saved comments
+ * @returns {Promise<Array<{path: string, name: string, location: string,
+ *   openedAt: string, exists: boolean, comments: number}>>}
+ */
+async function describeRecents(dataDir, commentCounts = new Map()) {
+  const projects = await readRecents(dataDir);
+
+  return Promise.all(
+    projects.map(async project => ({
+      path: project.path,
+      name: repoSlug(project.path),
+      // Where it lives, rather than all of where it lives. The name is on the
+      // row already, and two checkouts are told apart by the directory holding
+      // them, not by the forty characters they have in common.
+      location: homeRelative(pathModule.dirname(project.path)),
+      openedAt: project.openedAt,
+      exists: await fs
+        .stat(project.path)
+        .then(stats => stats.isDirectory())
+        .catch(() => false),
+      comments: commentCounts.get(canonicalRepoPath(project.path)) ?? 0
+    }))
+  );
+}
+
+module.exports = { readRecents, recordRecent, describeRecents, RECENTS_FILE, LIMIT };

package/lib/repo.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const path = require('path');
+
+const simpleGit = require('simple-git');
+
+/**
+ * Finding the repository a directory belongs to.
+ *
+ * Everything downstream of this — the session, the saved review's filename,
+ * every diff — is keyed on one path, and that path has to be the root of the
+ * working tree rather than wherever the person happened to be standing. Two
+ * things go wrong otherwise, and neither announces itself:
+ *
+ *   - `git status --porcelain` reports paths relative to the root, but a
+ *     pathspec is resolved relative to the process's directory. Ask a git
+ *     rooted at `repo/src` for `git diff -- src/deep/file.txt` and you get an
+ *     empty string back, not an error. The file is listed, the diff is blank,
+ *     and nothing says why.
+ *   - reviews are filed under a fingerprint of the repository path, so a
+ *     review written from the root is invisible from a subdirectory. The
+ *     browser saves it, `reviewer export` run one directory down reports that
+ *     no review exists, and the loop in the README quietly stops working.
+ */
+
+/**
+ * The root of the working tree containing `dir`.
+ *
+ * Answers `null` rather than raising for every way this can fail — not a
+ * repository, a bare repository with no working tree, git not installed, the
+ * directory gone. Callers decide what an absent repository means; for some it
+ * is an error and for others it is simply a directory they will use as given.
+ *
+ * The `simpleGit()` call is inside the `try` on purpose. It throws
+ * *synchronously, at construction* when the directory does not exist, so a
+ * `.catch()` on the returned promise never runs — the same trap documented at
+ * `readGitPosition` in `lib/export.js`.
+ *
+ * @param {string} dir any directory inside the repository
+ * @param {(dir: string) => import('simple-git').SimpleGit} [gitFactory]
+ * @returns {Promise<string|null>} absolute path to the root, or null
+ */
+async function repoRoot(dir, gitFactory = simpleGit) {
+  try {
+    const top = await gitFactory(dir).revparse(['--show-toplevel']);
+    const trimmed = String(top).trim();
+    return trimmed === '' ? null : path.resolve(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { repoRoot };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "git-reviewer",
-  "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",
+  "version": "2.3.0",
+  "description": "Review your coding agent's changes like a pull request — 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",
@@ -31,7 +31,8 @@
   },
   "main": "server.js",
   "bin": {
-    "reviewer": "bin/reviewer.js"
+    "reviewer": "bin/reviewer.js",
+    "git-reviewer": "bin/reviewer.js"
   },
   "files": [
     "bin/",