git-reviewer 2.0.0

package/lib/review.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { groupByFile } = require('./comments');
+
+/**
+ * Rendering a set of comments into the Markdown review file, and naming the
+ * files that hold a repository's review state.
+ */
+
+/**
+ * Make a repository name safe to embed in a filename.
+ *
+ * A repository directory can be named anything the filesystem allows, and that
+ * name goes straight into a filename under `reviews/`. Anything outside a
+ * conservative set becomes `_` so the result stays a single, predictable path
+ * segment.
+ *
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function repoSlug(repoPath) {
+  const base = path.basename(String(repoPath ?? '').replace(/[/\\]+$/, ''));
+  const slug = base.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+  return slug === '' ? 'repo' : slug;
+}
+
+/**
+ * Resolve a repository path to the one canonical form that identifies it.
+ *
+ * Two paths that name the same repository must produce the same answer, or the
+ * same review ends up under two names: `/work/api`, `/work/api/`, and a symlink
+ * pointing at either are one repository, not three. `realpath` is what settles
+ * the symlink case; it is allowed to fail, because naming a directory that does
+ * not exist yet is not an error here.
+ *
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function canonicalRepoPath(repoPath) {
+  const resolved = path.resolve(String(repoPath ?? ''));
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+/**
+ * Identify a repository's review state uniquely.
+ *
+ * The readable slug alone is only the directory's basename, so two checkouts
+ * both called `api-service` name the same file and the second review silently
+ * destroys the first. The suffix is derived from the full canonical path, which
+ * is what actually distinguishes them. The slug is kept in front so the
+ * directory stays browsable by a human.
+ *
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function repoKey(repoPath) {
+  // Both halves come from the canonical path. Taking the readable half from
+  // the path as written would undo the work: a symlink named `api` pointing at
+  // a checkout named `api-service` would agree on the fingerprint and still
+  // land in a different file.
+  const canonical = canonicalRepoPath(repoPath);
+  const fingerprint = crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 12);
+  return `${repoSlug(canonical)}-${fingerprint}`;
+}
+
+/**
+ * Name of the JSON file holding a repository's saved comments.
+ *
+ * This file is the source of truth for a review: the UI writes it on every
+ * edit and the submitted `.txt` is rendered from it.
+ *
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function commentsFilename(repoPath) {
+  return `.code-review-comments-${repoKey(repoPath)}.json`;
+}
+
+/**
+ * The pre-collision-fix name for a repository's saved comments.
+ *
+ * Reviews written before the path fingerprint existed live under this name.
+ * Nothing writes it any more; {@link module:lib/store} reads it once so an
+ * existing review is adopted rather than abandoned.
+ *
+ * @param {string} repoPath
+ * @returns {string}
+ */
+function legacyCommentsFilename(repoPath) {
+  return `.code-review-comments-${repoSlug(repoPath)}.json`;
+}
+
+/**
+ * Name of a submitted review file.
+ *
+ * The timestamp is derived from the ISO form so the names sort chronologically
+ * and contain no characters that need quoting.
+ *
+ * @param {string} repoPath
+ * @param {Date} generatedAt
+ * @returns {string}
+ */
+function reviewFilename(repoPath, generatedAt) {
+  const stamp = generatedAt.toISOString().replace(/[:.]/g, '-').replace('T', '_');
+  return `review_${repoKey(repoPath)}_${stamp}.txt`;
+}
+
+/**
+ * Render comments as the Markdown body of a review.
+ *
+ * Timestamps are written in ISO 8601 rather than a locale format: a review is
+ * a file that gets committed, pasted into a pull request, and read on another
+ * machine, so it must not change shape with the reader's locale or timezone.
+ *
+ * @param {object} args
+ * @param {string} args.repoPath repository the review covers
+ * @param {import('./comments').Comment[]} args.comments
+ * @param {Date} args.generatedAt
+ * @returns {string}
+ */
+function formatReview({ repoPath, comments, generatedAt }) {
+  const sections = [
+    '# Code Review\n',
+    `Repository: ${repoPath}`,
+    `Generated: ${generatedAt.toISOString()}`,
+    `Total Comments: ${comments.length}\n`
+  ];
+
+  for (const [file, fileComments] of groupByFile(comments)) {
+    sections.push(`## ${file}\n`);
+    for (const comment of fileComments) {
+      sections.push(formatComment(comment));
+    }
+  }
+
+  return `${sections.join('\n')}`;
+}
+
+/**
+ * @param {import('./comments').Comment} comment
+ * @returns {string}
+ */
+function formatComment(comment) {
+  const parts = [`**Line ${comment.line}:**`];
+
+  if (comment.lineContent) {
+    parts.push(fence(comment.lineContent));
+  }
+
+  if (comment.selectedText) {
+    parts.push('**Selected code:**', fence(comment.selectedText));
+  }
+
+  parts.push(comment.text);
+
+  if (comment.followUps?.length > 0) {
+    parts.push('', '**Follow-ups:**');
+    comment.followUps.forEach((followUp, index) => {
+      const timestamp = formatTimestamp(followUp.timestamp);
+      parts.push(`  ${index + 1}. ${followUp.text}${timestamp ? ` (${timestamp})` : ''}`);
+    });
+  }
+
+  return `${parts.join('\n')}\n`;
+}
+
+/**
+ * Wrap text in a fenced code block, widening the fence if the text itself
+ * contains one.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+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));
+  return `${marker}\n${text}\n${marker}`;
+}
+
+/**
+ * @param {string|undefined} timestamp
+ * @returns {string} ISO 8601 form, or '' when absent or unparseable
+ */
+function formatTimestamp(timestamp) {
+  if (!timestamp) return '';
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? '' : date.toISOString();
+}
+
+module.exports = {
+  formatReview,
+  reviewFilename,
+  commentsFilename,
+  legacyCommentsFilename,
+  repoSlug,
+  repoKey,
+  canonicalRepoPath
+};

package/lib/sessions.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * In-memory record of which repository each browser session is reviewing.
+ *
+ * Sessions live only as long as the process: the desktop app starts a fresh
+ * server per launch, and the web mode is a local single-user tool. Nothing
+ * here is persisted, so a restart simply asks the user to reopen the repo.
+ */
+
+/**
+ * @typedef {'working'|'lastCommit'} ReviewMode
+ * `working` diffs the working tree against HEAD; `lastCommit` diffs HEAD
+ * against its parent, which is what a clean tree falls back to.
+ */
+
+class SessionStore {
+  /**
+   * @param {() => string} [generateId] injectable for deterministic tests
+   */
+  constructor(generateId = () => crypto.randomBytes(8).toString('hex')) {
+    this.generateId = generateId;
+    /** @type {Map<string, {repoPath: string, mode: ReviewMode}>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @param {string} repoPath absolute path of the opened repository
+   * @param {ReviewMode} mode
+   * @returns {string} the new session id
+   */
+  create(repoPath, mode) {
+    const repoId = this.generateId();
+    this.sessions.set(repoId, { repoPath, mode });
+    return repoId;
+  }
+
+  /**
+   * @param {string} repoId
+   * @returns {{repoPath: string, mode: ReviewMode}|undefined}
+   */
+  get(repoId) {
+    return this.sessions.get(repoId);
+  }
+
+  /**
+   * @param {string} repoId
+   * @returns {boolean} whether a session was removed
+   */
+  delete(repoId) {
+    return this.sessions.delete(repoId);
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.sessions.size;
+  }
+}
+
+module.exports = { SessionStore };

package/lib/store.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+
+const { commentsFilename, legacyCommentsFilename, canonicalRepoPath } = require('./review');
+
+/**
+ * Reading a repository's saved comments, whatever name they were written under.
+ *
+ * There is exactly one rule here: a review is served to the repository it was
+ * written for, or not at all. Comment files used to be named after the
+ * repository's basename alone, so two checkouts called `api-service` shared one
+ * file — the second review overwrote the first, and every reader afterwards
+ * handed one repository's comments out under the other's name. Filenames now
+ * carry a fingerprint of the full path, and this module is the single place
+ * that decides which file answers for a repository.
+ */
+
+/** A comment file that belongs to a different repository than the one asking. */
+class ReviewOwnershipError extends Error {
+  /**
+   * @param {string} requested repository being opened
+   * @param {string} owner repository the file records itself as belonging to
+   */
+  constructor(requested, owner) {
+    super(
+      `The saved review in this file was written for ${owner}, not ${requested}. ` +
+        'Refusing to serve one repository\'s review under another\'s name.'
+    );
+    this.name = 'ReviewOwnershipError';
+    this.requested = requested;
+    this.owner = owner;
+  }
+}
+
+/**
+ * Whether a stored `repoPath` names the repository being opened.
+ *
+ * Files written before the fingerprint existed, and those written by tests,
+ * may carry no `repoPath` at all. An absent owner is not a mismatch — there is
+ * simply nothing to check — and the filename is doing the identifying.
+ *
+ * @param {string|undefined} stored
+ * @param {string} repoPath
+ * @returns {boolean}
+ */
+function belongsTo(stored, repoPath) {
+  if (typeof stored !== 'string' || stored === '') return true;
+  return canonicalRepoPath(stored) === canonicalRepoPath(repoPath);
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<object|null>} parsed contents, or null when absent
+ */
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf-8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * Read the comments saved for a repository.
+ *
+ * Looks under the current name first. Falling back to the legacy name is the
+ * migration: a review written before this change is adopted, but only when the
+ * file says it belongs to this repository — the whole point of the legacy name
+ * is that two repositories could share it, so adopting one blindly would
+ * reintroduce the bug it is here to fix.
+ *
+ * @param {string} reviewsDir
+ * @param {string} repoPath
+ * @returns {Promise<{comments: object[], adopted: boolean}>}
+ * @throws {ReviewOwnershipError} when the current file names another repository
+ */
+async function readSavedComments(reviewsDir, repoPath) {
+  const current = path.join(reviewsDir, commentsFilename(repoPath));
+  const saved = await readJson(current);
+
+  if (saved !== null) {
+    // The fingerprint should already have kept these apart. Checking anyway is
+    // cheap, and the failure it guards against is silent corruption.
+    if (!belongsTo(saved.repoPath, repoPath)) {
+      throw new ReviewOwnershipError(repoPath, saved.repoPath);
+    }
+    return { comments: saved.comments ?? [], adopted: false };
+  }
+
+  const legacyName = legacyCommentsFilename(repoPath);
+  if (legacyName === commentsFilename(repoPath)) return { comments: [], adopted: false };
+
+  const legacy = await readJson(path.join(reviewsDir, legacyName));
+  if (legacy === null || !belongsTo(legacy.repoPath, repoPath)) {
+    return { comments: [], adopted: false };
+  }
+
+  // Move it under the new name so the next read is a plain hit and the old
+  // name stops shadowing another checkout. A read-only reviews directory is
+  // not a reason to withhold the review, so a failed rename is not fatal.
+  try {
+    await fs.rename(path.join(reviewsDir, legacyName), current);
+  } catch {
+    /* the comments are already in hand; renaming is housekeeping */
+  }
+
+  return { comments: legacy.comments ?? [], adopted: true };
+}
+
+module.exports = { readSavedComments, ReviewOwnershipError, belongsTo };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "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",
+  "author": "Dheeraj Jha",
+  "license": "MIT",
+  "homepage": "https://github.com/dheerajjha/reviewer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dheerajjha/reviewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dheerajjha/reviewer/issues"
+  },
+  "keywords": [
+    "code-review",
+    "git",
+    "diff",
+    "review",
+    "cli",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "server.js",
+  "bin": {
+    "reviewer": "bin/reviewer.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "public/",
+    "server.js"
+  ],
+  "scripts": {
+    "start": "node bin/reviewer.js",
+    "serve": "node server.js",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "test:coverage": "node --test --experimental-test-coverage"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "simple-git": "^3.20.0"
+  }
+}