git-reviewer 2.11.0 → 2.13.0

package/server.js

@@ -12,7 +12,7 @@ const {
   resolveRepoFile,
   PathEscapeError
 } = require('./lib/paths');
-const { collectWorkingChanges, collectCommitChanges } = require('./lib/changes');
+const { collectWorkingChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
 const { normalizeComments } = require('./lib/comments');
 const { formatReview, reviewFilename, commentsFilename } = require('./lib/review');
@@ -68,6 +68,16 @@ class FileNotFoundError extends Error {
 // typing a ref, which is what the text box is for.
 const COMMIT_LIST_LIMIT = 30;
 
+// Branches and tags offered per group. A repository with two hundred stale
+// branches should still produce a list someone can scan; the ones past the
+// cut are the least recently touched and are still reachable by typing.
+const REF_LIST_LIMIT = 40;
+
+// How many commits the commits list shows. A branch of more than this is a
+// review nobody is doing commit by commit; the list says it is truncated
+// rather than pretending the rest are not there.
+const LOG_LIMIT = 200;
+
 function createApp(options = {}) {
   const {
     reviewsDir = resolveReviewsDir(),
@@ -128,10 +138,18 @@ function createApp(options = {}) {
     const absolutePath = resolveRepoFile(session.repoPath, filePath);
 
     if (session.range) {
+      // A range is two commits, and the working tree is neither of them. It
+      // used to be the fallback here, which was merely odd while the head of
+      // every range was HEAD and is wrong now that it can be another branch:
+      // Full Context on feature/billing, opened from a checkout of
+      // feature/auth, would show auth's copy of the file under billing's name.
+      //
+      // A path missing at the head was deleted inside the range, and the text
+      // worth showing is the text that was deleted.
       try {
         return await git.show([`${session.range.head}:${filePath}`]);
       } catch {
-        return await fs.readFile(absolutePath, 'utf-8').catch(() => '');
+        return git.show([`${session.range.from}:${filePath}`]).catch(() => '');
       }
     }
 
@@ -205,7 +223,7 @@ function createApp(options = {}) {
 
   async function diffForFile(git, session, filePath) {
     if (session.range) {
-      return git.diff([session.range.base, session.range.head, '--', filePath]);
+      return git.diff([session.range.from, session.range.head, '--', filePath]);
     }
     if (!(await hasCommits(git))) {
       return '';
@@ -251,7 +269,7 @@ function createApp(options = {}) {
       }
     }
 
-    const resolve = async (label, ref) => {
+    const resolve = async ref => {
       try {
         return (await git.revparse([`${ref}^{commit}`])).trim();
       } catch {
@@ -259,19 +277,151 @@ function createApp(options = {}) {
       }
     };
 
-    const baseSha = await resolve('base', base);
-    const headSha = await resolve('head', head);
-
-    // `base..head` counts what head has and base does not, which is the
-    // number a reviewer means by "how many commits am I looking at". It is
-    // not symmetric, and it is not the same as the file count -- a range
-    // whose changes cancel out has commits and no files, which is the whole
-    // reason this number is reported.
-    const commits = Number(
-      (await git.raw(['rev-list', '--count', `${baseSha}..${headSha}`])).trim()
+    const baseSha = await resolve(base);
+    const headSha = await resolve(head);
+
+    // The diff starts at the merge base, not at `base` itself -- what a pull
+    // request shows, and for the same reason. Compare feature/auth against a
+    // main that has moved on since the branch was cut, and a plain
+    // `git diff main feature/auth` includes main's newer commits *reversed*:
+    // the review then shows the feature author "undoing" a change they never
+    // touched, and a reviewer comments on it. On straight-line history the
+    // merge base of an ancestor and its descendant is the ancestor, so this
+    // changes nothing for x1..x5.
+    //
+    // Unrelated histories have no merge base; the plain two-ended diff is the
+    // only answer there, and it is the one given.
+    const from = await git.raw(['merge-base', baseSha, headSha])
+      .then(out => out.trim() || baseSha)
+      .catch(() => baseSha);
+
+    // `base..head` is what head has and base does not -- exactly the commits
+    // whose changes are in the diff. `head..base` is the other direction: what
+    // base has moved on by, which the merge-base diff deliberately leaves out
+    // and which the page has to say it left out, or someone will go looking
+    // for main's change and conclude the tool lost it.
+    const count = async range => Number(
+      (await git.raw(['rev-list', '--count', range])).trim()
     );
+    const commits = await count(`${baseSha}..${headSha}`);
+    const behind = await count(`${headSha}..${baseSha}`);
+
+    // What the person asked for, kept alongside the SHAs. Nobody chose
+    // `3eb57959`; they chose `main`, and a scope bar that answers in SHAs has
+    // translated their question into one they did not ask.
+    const nameOf = async ref => {
+      if (ref !== 'HEAD') return ref;
+      const branch = await git.revparse(['--abbrev-ref', 'HEAD']).then(b => b.trim()).catch(() => 'HEAD');
+      return branch === 'HEAD' ? headSha.slice(0, 8) : branch;
+    };
+
+    return {
+      base: baseSha,
+      head: headSha,
+      from,
+      commits: Number.isFinite(commits) ? commits : 0,
+      behind: Number.isFinite(behind) ? behind : 0,
+      baseName: await nameOf(base),
+      headName: await nameOf(head)
+    };
+  }
+
+  /**
+   * The range for reviewing commits themselves: one, or an unbroken run.
+   *
+   * Different from comparing two refs. `from` and `to` are both *in* the
+   * review -- clicking one commit means that commit's changes, and
+   * shift-clicking a second means everything from the first through the
+   * second -- so the diff starts at the parent of `from`, not at `from`.
+   * That is what GitHub does when you pick commits inside a pull request, and
+   * what "review commit 3 of 5" has to mean.
+   *
+   * `from` has to come before `to` on one line of history. Two commits on
+   * different branches have no run between them; that is a comparison, and
+   * the compare pickers exist for it.
+   *
+   * @throws {Error} with a message meant for the page
+   */
+  async function resolveCommitRun(git, fromRef, toRef) {
+    for (const [label, ref] of [['first commit', fromRef], ['last commit', toRef]]) {
+      if (!looksLikeRef(ref)) throw new Error(`That ${label} does not look like a commit.`);
+    }
+
+    const resolve = async ref => {
+      try {
+        return (await git.revparse([`${ref}^{commit}`])).trim();
+      } catch {
+        throw new Error(`No commit called "${ref}" in this repository.`);
+      }
+    };
+    const first = await resolve(fromRef);
+    const last = await resolve(toRef);
+
+    // Ancestry through output, not exit code: `merge-base --is-ancestor`
+    // answers only by exiting 1, and simple-git resolves a silent non-zero
+    // exit -- so it reported every pair as ordered, including main before a
+    // branch that main was not an ancestor of. The merge base of an ancestor
+    // and its descendant is the ancestor, and that is checkable.
+    const mergeBase = (await git.raw(['merge-base', first, last]).catch(() => '')).trim();
+    if (mergeBase !== first) {
+      throw new Error(
+        `${first.slice(0, 7)} does not come before ${last.slice(0, 7)} on one line of history, ` +
+        'so there is no run of commits between them. Use Compare to diff two unrelated points.'
+      );
+    }
+
+    // A root commit has no parent. Its "before" is the empty tree, which is
+    // also how `git show` presents a root commit: every file added.
+    let from;
+    let hasParent = true;
+    try {
+      from = (await git.revparse([`${first}^`])).trim();
+    } catch {
+      hasParent = false;
+      from = (await git.raw(['hash-object', '-t', 'tree', '/dev/null'])).trim();
+    }
 
-    return { base: baseSha, head: headSha, commits: Number.isFinite(commits) ? commits : 0 };
+    const count = Number((await git.raw(['rev-list', '--count', hasParent ? `${from}..${last}` : last, '--'])).trim());
+    const subject = first === last
+      ? (await git.raw(['log', '-1', '--format=%s', last, '--']).catch(() => '')).trim()
+      : null;
+
+    return {
+      kind: 'commits',
+      first,
+      last,
+      base: from,
+      head: last,
+      from,
+      commits: Number.isFinite(count) ? count : 1,
+      behind: 0,
+      baseName: first.slice(0, 7),
+      headName: last.slice(0, 7),
+      ...(subject ? { subject } : {})
+    };
+  }
+
+  /** What to say about a commit or a run of them once loaded. */
+  function describeCommitRun(range, fileCount) {
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+    const files = fileCount === 0 ? 'no files changed' : plural(fileCount, 'changed file');
+    return range.first === range.last
+      ? `Commit ${range.headName}${range.subject ? `: ${range.subject}` : ''} — ${files}`
+      : `${plural(range.commits, 'commit')}, ${range.baseName} through ${range.headName} — ${files}`;
+  }
+
+  /**
+   * The changed files of a range, with the status git gives each one.
+   *
+   * @param {import('simple-git').SimpleGit} git
+   * @param {{from: string, head: string}} range
+   */
+  async function collectRangeChanges(git, range) {
+    const [summary, nameStatus] = await Promise.all([
+      git.diffSummary([range.from, range.head]),
+      git.raw(['diff', '--name-status', '-z', '-M', range.from, range.head])
+    ]);
+    return collectCommitChanges(summary, parseNameStatus(nameStatus));
   }
 
   /**
@@ -288,15 +438,20 @@ function createApp(options = {}) {
    * @returns {string}
    */
   function describeRange(range, fileCount) {
-    const commits = `${range.commits} commit${range.commits === 1 ? '' : 's'}`;
+    const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+    const ends = `${range.baseName ?? range.base.slice(0, 8)} \u2192 ${range.headName ?? range.head.slice(0, 8)}`;
+
+    if (fileCount > 0) {
+      return `${ends}: ${plural(range.commits, 'commit')}, ${plural(fileCount, 'changed file')}`;
+    }
 
-    if (fileCount === 0) {
-      return range.commits === 0
-        ? 'Those two commits are the same, so there is nothing between them.'
-        : `${commits}, and no net change between the two ends — every change in them was undone again inside the range.`;
+    if (range.commits === 0) {
+      return range.behind === 0
+        ? `${ends}: both point at the same commit, so there is nothing between them.`
+        : `${ends}: ${range.headName ?? 'the head'} has no commits that ${range.baseName ?? 'the base'} does not already have.`;
     }
 
-    return `${commits}, ${fileCount} changed file${fileCount === 1 ? '' : 's'} between the two ends`;
+    return `${ends}: ${plural(range.commits, 'commit')}, and no net change \u2014 every change in them was undone again inside the range.`;
   }
 
   /**
@@ -316,9 +471,9 @@ function createApp(options = {}) {
    * @param {import('simple-git').SimpleGit} git
    * @param {number} limit
    */
-  async function recentCommits(git, limit) {
+  async function recentCommits(git, limit, head = 'HEAD') {
     const raw = await git.raw([
-      'log', `--max-count=${limit}`, '--format=%H%x00%h%x00%s%x00%cr'
+      'log', `--max-count=${limit}`, '--format=%H%x00%h%x00%s%x00%cr', head, '--'
     ]);
 
     return raw
@@ -331,7 +486,138 @@ function createApp(options = {}) {
   }
 
   /**
-   * The commits of an open repository, newest first.
+   * Everything the compare pickers offer: branches, tags and recent commits.
+   *
+   * Branches come first in the page because comparing branches is what people
+   * reach for -- "what does my branch change against main" -- and a picker
+   * that only lists commits of the current branch makes that the one
+   * comparison you cannot pick. Remote-tracking branches are included because
+   * `origin/main` is the base most reviews actually want, and a local `main`
+   * that has not been pulled in a week is a quietly wrong one.
+   *
+   * Sorted by most recent activity, so the branch you are working on and the
+   * one you branched from are near the top rather than alphabetised into the
+   * middle of forty others.
+   */
+  app.get('/api/refs/:repoId', async (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+
+    const git = gitFactory(session.repoPath);
+    const refList = async (pattern, limit) => {
+      try {
+        const raw = await git.raw([
+          'for-each-ref', `--count=${limit}`, '--sort=-committerdate',
+          '--format=%(refname:short)%00%(objectname)%00%(committerdate:relative)%00%(subject)%00%(symref)',
+          pattern
+        ]);
+        return raw.split('\n').filter(Boolean).map(line => {
+          const [name, sha, when, subject, symref] = line.split('\u0000');
+          return { name, sha, when, subject, symref };
+        })
+          // A symbolic ref points at another ref rather than being one --
+          // `origin/HEAD` in every clone. It cannot be filtered by name:
+          // `refname:short` abbreviates it to plain `origin`, which is how it
+          // first slipped into the list as a "branch".
+          .filter(ref => !ref.symref)
+          .map(({ symref, ...ref }) => ref);
+      } catch {
+        return [];
+      }
+    };
+
+    const current = await git.revparse(['--abbrev-ref', 'HEAD']).then(b => b.trim()).catch(() => null);
+
+    // The commits offered are the history of whatever is being compared, not
+    // always of the checkout: comparing main against feature/billing from a
+    // checkout of feature/auth should offer billing's commits to pick from.
+    const requested = typeof req.query.head === 'string' ? req.query.head.trim() : '';
+    const head = requested && looksLikeRef(requested) ? requested : 'HEAD';
+
+    const [branches, remotes, tags, commits] = await Promise.all([
+      refList('refs/heads', REF_LIST_LIMIT),
+      refList('refs/remotes', REF_LIST_LIMIT),
+      refList('refs/tags', REF_LIST_LIMIT),
+      recentCommits(git, COMMIT_LIST_LIMIT, head).catch(() => [])
+    ]);
+
+    res.json({
+      // `HEAD` from --abbrev-ref means detached; say so rather than pretend
+      // there is a branch called HEAD.
+      current: current === 'HEAD' ? null : current,
+      branches,
+      remotes,
+      tags,
+      commits
+    });
+  });
+
+  /**
+   * The commits a review can be narrowed to, one at a time or as a run.
+   *
+   * With a base: the commits the comparison is made of -- what `base..head`
+   * has -- oldest first, because a branch reads as a story in the order it
+   * was written, and stepping through it commit by commit is the point.
+   * Without one: the recent history of `head`, newest first, the way `git
+   * log` reads, because there is no story there, only "how far back".
+   *
+   * Each commit carries its full message. The subject is what fits in a
+   * list, but the body is often where the author explains the change, and a
+   * reviewer looking at one commit should not have to leave the tool to read
+   * why it was made.
+   *
+   * Records are split on %x1e rather than on newlines, because a commit body
+   * is made of newlines.
+   */
+  app.get('/api/log/:repoId', async (req, res) => {
+    const session = requireSession(res, req.params.repoId);
+    if (!session) return;
+
+    const git = gitFactory(session.repoPath);
+    const pick = name => (typeof req.query[name] === 'string' ? req.query[name].trim() : '');
+    const head = pick('head') || 'HEAD';
+    const base = pick('base');
+
+    for (const ref of base ? [base, head] : [head]) {
+      if (!looksLikeRef(ref)) {
+        return res.status(400).json({ error: 'That does not look like a commit or branch.' });
+      }
+    }
+
+    try {
+      const range = base ? `${base}..${head}` : head;
+      const total = Number((await git.raw(['rev-list', '--count', range, '--'])).trim()) || 0;
+      const raw = await git.raw([
+        'log', `--max-count=${LOG_LIMIT}`, ...(base ? ['--reverse'] : []),
+        '--format=%H%x00%h%x00%s%x00%an%x00%cr%x00%P%x00%b%x1e', range, '--'
+      ]);
+
+      const commits = raw.split('\u001e').map(record => record.replace(/^\n/, '')).filter(Boolean).map(record => {
+        const [sha, short, subject, author, when, parents, body] = record.split('\u0000');
+        return {
+          sha, short, subject, author, when,
+          body: (body ?? '').trim(),
+          // A merge is shown against its first parent when reviewed alone --
+          // what it brought in -- and the list says it is one, because that
+          // diff can be surprisingly large.
+          merge: (parents ?? '').trim().split(/\s+/).filter(Boolean).length > 1
+        };
+      });
+
+      res.json({
+        order: base ? 'oldest-first' : 'newest-first',
+        total,
+        truncated: total > commits.length,
+        commits
+      });
+    } catch {
+      res.status(400).json({ error: `Could not read the history of "${base ? `${base}..${head}` : head}".` });
+    }
+  });
+
+  /**
+   * The commits of an open repository, newest first. Kept for 2.11 callers;
+   * the page itself uses /api/refs and /api/log.
    *
    * Behind a session id like the file endpoints rather than taking a path:
    * this reads history out of a repository, and the session is what says
@@ -482,7 +768,7 @@ function createApp(options = {}) {
       // Resolve to the root of the working tree before anything is keyed on
       // this path. A subdirectory passes `checkIsRepo()` quite happily and
       // then produces a file list whose diffs are all empty; see lib/repo.js.
-      const { base, head } = req.body ?? {};
+      const { base, head, commits: run } = req.body ?? {};
       const root = await repoRoot(repoPath, gitFactory);
       if (!root) {
         return res.status(400).json({ error: 'Not a valid git repository' });
@@ -495,7 +781,18 @@ function createApp(options = {}) {
       let range = null;
       let message;
 
-      if (base !== undefined && base !== null && `${base}`.trim() !== '') {
+      if (run && typeof run === 'object') {
+        // Commits themselves, one or a run: see resolveCommitRun.
+        try {
+          range = await resolveCommitRun(git, `${run.from ?? ''}`.trim(), `${run.to ?? run.from ?? ''}`.trim());
+        } catch (error) {
+          return res.status(400).json({ error: error.message });
+        }
+
+        files = await collectRangeChanges(git, range);
+        mode = 'range';
+        message = describeCommitRun(range, files.length);
+      } else if (base !== undefined && base !== null && `${base}`.trim() !== '') {
         // An explicit range. Nothing falls back to anything here: someone who
         // asked for x1..x3 and is silently shown their working tree instead
         // has been told a lie about what they are reviewing.
@@ -505,7 +802,7 @@ function createApp(options = {}) {
           return res.status(400).json({ error: error.message });
         }
 
-        files = collectCommitChanges(await git.diffSummary([range.base, range.head]));
+        files = await collectRangeChanges(git, range);
         mode = 'range';
         message = describeRange(range, files.length);
       } else {
@@ -517,9 +814,7 @@ function createApp(options = {}) {
         if (files.length === 0) {
           try {
             const lastCommit = await resolveRange(git, 'HEAD~1', 'HEAD');
-            const commitFiles = collectCommitChanges(
-              await git.diffSummary([lastCommit.base, lastCommit.head])
-            );
+            const commitFiles = await collectRangeChanges(git, lastCommit);
             if (commitFiles.length > 0) {
               files = commitFiles;
               mode = 'lastCommit';