git-reviewer 2.0.0

package/lib/changes.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * Turning git state into the flat `{ path, status }` list the file sidebar
+ * renders.
+ *
+ * Status letters follow git's own vocabulary: `A` added, `M` modified,
+ * `D` deleted, `R` renamed, `B` binary.
+ */
+
+/**
+ * @typedef {object} ChangedFile
+ * @property {string} path repo-relative path
+ * @property {'A'|'M'|'D'|'R'|'B'} status
+ */
+
+/**
+ * Collect working-directory changes from a `simple-git` status result.
+ *
+ * A single path can be reported by more than one bucket — a file that is
+ * staged and then edited again shows up as both created and modified — so the
+ * first status wins and later duplicates are dropped. Buckets are ordered
+ * most- to least-specific for that reason.
+ *
+ * @param {import('simple-git').StatusResult} status
+ * @returns {ChangedFile[]}
+ */
+function collectWorkingChanges(status) {
+  const buckets = [
+    [status?.renamed ?? [], 'R'],
+    [status?.deleted ?? [], 'D'],
+    [status?.created ?? [], 'A'],
+    [status?.not_added ?? [], 'A'],
+    [status?.modified ?? [], 'M']
+  ];
+
+  const seen = new Map();
+
+  for (const [files, letter] of buckets) {
+    for (const entry of files) {
+      // `renamed` holds `{ from, to }`; every other bucket holds plain strings.
+      const filePath = typeof entry === 'string' ? entry : entry?.to;
+      if (!filePath || seen.has(filePath)) continue;
+      seen.set(filePath, { path: filePath, status: letter });
+    }
+  }
+
+  return [...seen.values()];
+}
+
+/**
+ * Derive a status letter for one file of a commit diff summary.
+ *
+ * `simple-git` reports binary files without insertion/deletion counts, and a
+ * commit that only adds lines to a file is an addition of that file only when
+ * it deletes none.
+ *
+ * @param {object} file entry from `git.diffSummary()`
+ * @returns {'A'|'M'|'D'|'B'}
+ */
+function classifyCommitFile(file) {
+  if (file?.binary) return 'B';
+
+  const insertions = file?.insertions ?? 0;
+  const deletions = file?.deletions ?? 0;
+
+  if (insertions > 0 && deletions > 0) return 'M';
+  if (insertions > 0) return 'A';
+  if (deletions > 0) return 'D';
+  return 'M';
+}
+
+/**
+ * Collect the files touched by a commit.
+ *
+ * @param {import('simple-git').DiffResult} diffSummary
+ * @returns {ChangedFile[]}
+ */
+function collectCommitChanges(diffSummary) {
+  const files = diffSummary?.files ?? [];
+  return files.map(file => ({ path: file.file, status: classifyCommitFile(file) }));
+}
+
+module.exports = { collectWorkingChanges, collectCommitChanges, classifyCommitFile };

package/lib/cli.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Command-line parsing for the `reviewer` command.
+ *
+ * Kept separate from the command itself so the argument handling can be tested
+ * without starting a server or opening a browser.
+ */
+
+const USAGE = `reviewer — review local git changes in your browser
+
+Usage:
+  reviewer [repository] [options]
+  reviewer export [repository] [--format json|prompt] [--file <path>]
+
+Arguments:
+  repository        Path to a git repository. 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
+                    coding agent or another tool to consume.
+
+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
+  -f, --format <f>  Export format: json (default) or prompt
+      --file <path> Export comments for one repo-relative file
+  -h, --help        Show this help
+  -v, --version     Show the version
+
+Examples:
+  reviewer                 review the repository you are standing in
+  reviewer ~/work/api      review another repository
+  reviewer . --no-open     print the URL, open it yourself
+  reviewer export .        print the review as JSON
+  reviewer export . --file src/auth.js
+  reviewer export . --format prompt | claude -p "apply this review"
+`;
+
+/** Formats `reviewer export` can print. */
+const FORMATS = ['json', 'prompt'];
+
+class UsageError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * @typedef {object} CliOptions
+ * @property {'serve'|'export'} 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 {'json'|'prompt'} format for `export`
+ * @property {string|null} file repo-relative file to export, or all files
+ * @property {boolean} help
+ * @property {boolean} version
+ */
+
+/**
+ * Parse `reviewer` arguments.
+ *
+ * @param {string[]} argv arguments after the node binary and script
+ * @param {string} [cwd] base for resolving a relative repository path
+ * @returns {CliOptions}
+ * @throws {UsageError} on an unknown flag, a missing value, or a bad port
+ */
+function parseArgs(argv, cwd = process.cwd()) {
+  /** @type {CliOptions} */
+  const options = {
+    command: 'serve',
+    repoPath: null,
+    port: null,
+    open: true,
+    format: 'json',
+    file: null,
+    help: false,
+    version: false
+  };
+  let positional = 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`.
+  let rest = argv;
+  if (argv[0] === 'export') {
+    options.command = 'export';
+    rest = argv.slice(1);
+  }
+
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+
+      case '-v':
+      case '--version':
+        options.version = true;
+        break;
+
+      case '--no-open':
+        options.open = false;
+        break;
+
+      case '-p':
+      case '--port': {
+        const value = rest[++i];
+        if (value === undefined) throw new UsageError(`${arg} needs a port number`);
+        options.port = parsePort(value, arg);
+        break;
+      }
+
+      case '-f':
+      case '--format': {
+        const value = rest[++i];
+        if (value === undefined) throw new UsageError(`${arg} needs a format`);
+        options.format = parseFormat(value, arg);
+        break;
+      }
+
+      case '--file': {
+        const value = rest[++i];
+        options.file = parseFile(value, '--file');
+        break;
+      }
+
+      default: {
+        // Support --port=4500 as well as --port 4500.
+        const inlinePort = arg.match(/^--port=(.*)$/);
+        if (inlinePort) {
+          options.port = parsePort(inlinePort[1], '--port');
+          break;
+        }
+
+        const inlineFormat = arg.match(/^--format=(.*)$/);
+        if (inlineFormat) {
+          options.format = parseFormat(inlineFormat[1], '--format');
+          break;
+        }
+
+        const inlineFile = arg.match(/^--file=(.*)$/);
+        if (inlineFile) {
+          options.file = parseFile(inlineFile[1], '--file');
+          break;
+        }
+
+        if (arg.startsWith('-') && arg !== '-') {
+          throw new UsageError(`Unknown option: ${arg}`);
+        }
+
+        if (positional !== null) {
+          throw new UsageError(`Unexpected argument: ${arg}`);
+        }
+
+        positional = arg;
+      }
+    }
+  }
+
+  if (positional !== null) {
+    options.repoPath = path.resolve(cwd, positional);
+  }
+
+  if (options.file !== null && options.command !== 'export') {
+    throw new UsageError('--file is only valid with reviewer export');
+  }
+
+  return options;
+}
+
+/**
+ * @param {string} value
+ * @param {string} flag the flag being parsed, for the error message
+ * @returns {number}
+ */
+function parsePort(value, flag) {
+  // Number() rather than parseInt() so "80x" is rejected instead of read as 80
+  // — but Number('') is 0, and an empty value is a mistake, not a request for
+  // any free port.
+  const port = value.trim() === '' ? NaN : Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new UsageError(`${flag} must be a number between 0 and 65535, got "${value}"`);
+  }
+  return port;
+}
+
+/**
+ * @param {string} value
+ * @param {string} flag the flag being parsed, for the error message
+ * @returns {'json'|'prompt'}
+ */
+function parseFormat(value, flag) {
+  if (!FORMATS.includes(value)) {
+    throw new UsageError(`${flag} must be one of ${FORMATS.join(', ')}, got "${value}"`);
+  }
+  return value;
+}
+
+/**
+ * @param {string|undefined} value
+ * @param {string} flag the flag being parsed, for the error message
+ * @returns {string}
+ */
+function parseFile(value, flag) {
+  if (value === undefined || value.trim() === '' || value.startsWith('-')) {
+    throw new UsageError(`${flag} needs a repo-relative file path`);
+  }
+  return value;
+}
+
+/**
+ * Build the URL to open, asking the page to load a repository if one was named.
+ *
+ * @param {string} origin e.g. http://127.0.0.1:4500
+ * @param {string|null} repoPath
+ * @returns {string}
+ */
+function buildUrl(origin, repoPath) {
+  if (!repoPath) return origin;
+  return `${origin}/?repo=${encodeURIComponent(repoPath)}`;
+}
+
+module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS };

package/lib/comments.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * 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.
+ */
+
+/**
+ * @typedef {object} FollowUp
+ * @property {string} text
+ * @property {string} [timestamp] ISO 8601
+ */
+
+/**
+ * @typedef {object} Comment
+ * @property {string} file repo-relative path
+ * @property {number} line 1-based line number
+ * @property {string} [lineContent] the line the comment is anchored to
+ * @property {string} text
+ * @property {string} [selectedText] code the reviewer highlighted
+ * @property {FollowUp[]} [followUps]
+ */
+
+/**
+ * Reduce a client comment to the fields that get persisted.
+ *
+ * Optional fields are omitted rather than stored as `null` so that an absent
+ * selection and an empty one are not two different states on disk.
+ *
+ * @param {object} comment
+ * @returns {Comment}
+ */
+function normalizeComment(comment) {
+  const normalized = {
+    file: comment.file,
+    line: comment.line,
+    lineContent: comment.lineContent,
+    text: comment.text
+  };
+
+  if (comment.selectedText) {
+    normalized.selectedText = comment.selectedText;
+  }
+
+  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;
+    });
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize a batch of comments.
+ *
+ * @param {object[]} comments
+ * @returns {Comment[]}
+ * @throws {TypeError} when `comments` is not an array
+ */
+function normalizeComments(comments) {
+  if (!Array.isArray(comments)) {
+    throw new TypeError('comments must be an array');
+  }
+  return comments.map(normalizeComment);
+}
+
+/**
+ * Group comments by file, each group sorted by line number.
+ *
+ * Insertion order of the files is preserved so a review reads in the order the
+ * reviewer worked through the changes.
+ *
+ * @param {Comment[]} comments
+ * @returns {Array<[string, Comment[]]>}
+ */
+function groupByFile(comments) {
+  /** @type {Map<string, Comment[]>} */
+  const groups = new Map();
+
+  for (const comment of comments) {
+    const group = groups.get(comment.file);
+    if (group) group.push(comment);
+    else groups.set(comment.file, [comment]);
+  }
+
+  return [...groups.entries()].map(([file, group]) => [
+    file,
+    [...group].sort((a, b) => a.line - b.line)
+  ]);
+}
+
+module.exports = { normalizeComment, normalizeComments, groupByFile };

package/lib/diff.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Parsing of unified diff text into the line model the UI renders.
+ *
+ * The parser is deliberately tolerant: `git diff` output for a single file is
+ * the common case, but the same text can arrive with multiple `diff --git`
+ * sections (a caller that forgot to scope the diff to one path), with no hunks
+ * at all (an untracked file has nothing to diff against), or truncated.
+ */
+
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+
+/**
+ * @typedef {object} DiffLine
+ * @property {number|null} oldLine  1-based line number before the change
+ * @property {number|null} newLine  1-based line number after the change
+ * @property {'add'|'delete'|'unchanged'} type
+ * @property {string} content       the line without its diff marker
+ */
+
+/**
+ * Parse unified diff text into structured lines.
+ *
+ * When the diff contains no hunks the file is treated as wholly new and every
+ * line of `currentContent` is reported as an addition — that is what an
+ * untracked file looks like to the UI.
+ *
+ * @param {string} diffText unified diff, may be empty
+ * @param {string} currentContent full text of the file as it stands now
+ * @returns {DiffLine[]}
+ */
+function parseDiff(diffText, currentContent) {
+  const lines = [];
+  const diffLines = String(diffText ?? '').split('\n');
+
+  let oldLine = 0;
+  let newLine = 0;
+  let inHunk = false;
+
+  for (const line of diffLines) {
+    // A new file section ends the previous one. Without this the `---`/`+++`
+    // headers of the second file would be read as content of the first.
+    if (line.startsWith('diff --git ')) {
+      inHunk = false;
+      continue;
+    }
+
+    if (line.startsWith('@@')) {
+      const match = line.match(HUNK_HEADER);
+      if (match) {
+        oldLine = parseInt(match[1], 10);
+        newLine = parseInt(match[2], 10);
+        inHunk = true;
+      }
+      continue;
+    }
+
+    if (!inHunk) continue;
+
+    if (line.startsWith('-')) {
+      lines.push({ oldLine: oldLine++, newLine: null, type: 'delete', content: line.slice(1) });
+    } else if (line.startsWith('+')) {
+      lines.push({ oldLine: null, newLine: newLine++, type: 'add', content: line.slice(1) });
+    } else if (line.startsWith(' ')) {
+      lines.push({ oldLine: oldLine++, newLine: newLine++, type: 'unchanged', content: line.slice(1) });
+    }
+    // Anything else inside a hunk ("") carries no
+    // line of its own and is dropped.
+  }
+
+  if (lines.length > 0) return lines;
+
+  return wholeFileAsAdditions(currentContent);
+}
+
+/**
+ * Represent a file with no diff as one addition per line.
+ *
+ * @param {string} currentContent
+ * @returns {DiffLine[]}
+ */
+function wholeFileAsAdditions(currentContent) {
+  const content = String(currentContent ?? '');
+  if (content === '') return [];
+
+  return content
+    .split('\n')
+    .map((text, i) => ({ oldLine: null, newLine: i + 1, type: 'add', content: text }));
+}
+
+module.exports = { parseDiff, wholeFileAsAdditions, HUNK_HEADER };

package/lib/paths.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Confining request-supplied paths to the repository being reviewed.
+ */
+
+class PathEscapeError extends Error {
+  /** @param {string} requested the offending path, as received */
+  constructor(requested) {
+    super('Path escapes the repository');
+    this.name = 'PathEscapeError';
+    this.requested = requested;
+  }
+}
+
+/**
+ * Resolve a repo-relative path to an absolute one, refusing anything that
+ * lands outside the repository.
+ *
+ * The file endpoints take their path straight from the URL, so without this a
+ * request for `../../../../etc/passwd` would be served happily. Absolute paths
+ * are refused for the same reason: only files inside the opened repository are
+ * in scope for a review.
+ *
+ * @param {string} repoPath absolute path of the repository
+ * @param {string} filePath path relative to `repoPath`
+ * @returns {string} absolute path inside `repoPath`
+ * @throws {PathEscapeError} when the result would sit outside `repoPath`
+ */
+function resolveRepoFile(repoPath, filePath) {
+  const requested = String(filePath ?? '');
+
+  if (requested === '' || path.isAbsolute(requested)) {
+    throw new PathEscapeError(requested);
+  }
+
+  const root = path.resolve(repoPath);
+  const resolved = path.resolve(root, requested);
+
+  // `relative` is '' for the root itself and starts with '..' for anything
+  // above it. Comparing prefixes instead would accept a sibling `repo-evil`.
+  const relative = path.relative(root, resolved);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new PathEscapeError(requested);
+  }
+
+  return resolved;
+}
+
+module.exports = { resolveRepoFile, PathEscapeError };