@in-the-loop-labs/pair-review 3.4.1 → 3.5.0

package/src/external/github-adapter.js

@@ -0,0 +1,152 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+/**
+ * GitHub source adapter for external review comments.
+ *
+ * Two responsibilities:
+ *   1. `fetchComments` — delegate to the GitHubClient method that paginates
+ *      `pulls.listReviewComments`. Adapter does NOT construct its own client;
+ *      the caller injects it (dependency injection per CLAUDE.md).
+ *   2. `mapComment` — translate a raw GitHub REST API row into the column
+ *      shape of the `external_comments` table (see `src/database.js`).
+ *
+ * The dispatcher in `src/external/index.js` stamps `source = 'github'` at
+ * write time, so `mapComment` does not include a `source` field — keeps
+ * adapters from needing to know their own name.
+ *
+ * `synced_at` and the resolved local `parent_id` are also set by the
+ * route/repository layer, not here.
+ */
+
+const { GitHubClient, GitHubApiError } = require('../github/client');
+const { getGitHubToken } = require('../config');
+
+const name = 'github';
+
+/**
+ * Adapter-owned env var name. Surfaced in credential-missing errors so the
+ * user is told which env var/config key to set for THIS source. Future
+ * adapters (GitLab, Linear) name their own variable here and the route
+ * needs no per-source branching.
+ */
+const credentialEnvVar = 'GITHUB_TOKEN';
+
+/**
+ * Resolve the credentials this adapter needs to call its source system.
+ * Returns an opaque `{ client }` shape; the route hands `client` straight
+ * back to `fetchComments` without knowing it's a `GitHubClient`. Throwing
+ * `GitHubApiError(status: 401)` keeps the existing 401 mapping at the
+ * route layer.
+ *
+ * @param {Object} config - Server config (see `loadConfig()`)
+ * @param {Object} [_deps] - Test overrides for { GitHubClient, getGitHubToken }
+ * @returns {{ client: Object }}
+ * @throws {GitHubApiError} with status 401 when no token is configured
+ */
+function resolveCredentials(config, _deps) {
+  const deps = {
+    GitHubClient,
+    getGitHubToken,
+    ..._deps
+  };
+  const token = deps.getGitHubToken(config || {});
+  if (!token) {
+    throw new GitHubApiError(
+      `GitHub token not configured. Set ${credentialEnvVar} or add github_token to ~/.pair-review/config.json`,
+      401
+    );
+  }
+  return { client: new deps.GitHubClient(token) };
+}
+
+/**
+ * Fetch all inline review comments for a pull request from GitHub.
+ *
+ * @param {Object} params
+ * @param {Object} params.client - GitHubClient instance (injected)
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {number} params.pull_number
+ * @returns {Promise<Array<Object>>} Raw Octokit review-comment objects
+ */
+async function fetchComments({ client, owner, repo, pull_number }) {
+  return client.listReviewComments({ owner, repo, pull_number });
+}
+
+/**
+ * Map a raw GitHub review-comment API row to an `external_comments` row.
+ *
+ * Edge cases handled here (per the phase spec):
+ *   - `apiRow.user` is null (deleted account): `author` and `author_url`
+ *     both become null. No throw.
+ *   - `apiRow.position` is null (outdated): `is_outdated = 1`, current
+ *     line/position fields null. `original_*` may still be populated.
+ *   - `apiRow.position` AND `apiRow.original_position` both null
+ *     (force-push lost anchor): still produces a row — the sync route
+ *     decides whether to count or skip. We do NOT throw here.
+ *   - `apiRow.path` missing: throws — `file` is NOT NULL in the schema
+ *     and a missing path means upstream gave us something malformed.
+ *     Failing early in the mapper is far easier to debug than a SQL
+ *     constraint violation deep in an upsert loop.
+ *
+ * @param {Object} apiRow
+ * @returns {Object} A row matching the `external_comments` column names
+ */
+function mapComment(apiRow) {
+  if (!apiRow || apiRow.path == null) {
+    throw new Error('GitHub adapter: comment missing required field "path"');
+  }
+  // Validate id presence — `String(undefined)` returns the literal
+  // 'undefined' which would upsert as a valid external_id and even
+  // satisfy UNIQUE(review_id, source, external_id) by colliding on that
+  // string. Fail early so the route's row-level catch logs the bad row
+  // and moves on instead of corrupting the mirror.
+  if (apiRow.id == null) {
+    throw new Error('GitHub adapter: comment missing required field "id"');
+  }
+
+  const user = apiRow.user || null;
+  const positionIsNull = apiRow.position == null;
+
+  // When position is null the comment is outdated. GitHub still populates
+  // `line` in many of these responses, but the line number does NOT
+  // correspond to a position in the current diff — using it would create
+  // two conflicting truths (line_end set AND is_outdated=1) and would
+  // make the lost-anchor filter under-count. Force the current-anchor
+  // fields to null so `original_*` is the only authoritative anchor.
+  const line_start = positionIsNull
+    ? null
+    : apiRow.start_line ?? apiRow.line ?? null;
+  const line_end = positionIsNull ? null : apiRow.line ?? null;
+  const diff_position = positionIsNull ? null : apiRow.position ?? null;
+
+  return {
+    external_id: String(apiRow.id),
+    in_reply_to_id:
+      apiRow.in_reply_to_id != null ? String(apiRow.in_reply_to_id) : null,
+    external_url: apiRow.html_url || null,
+    author: user ? user.login ?? null : null,
+    author_url: user ? user.html_url ?? null : null,
+    file: apiRow.path,
+    side: apiRow.side ?? null,
+    line_start,
+    line_end,
+    diff_position,
+    commit_sha: apiRow.commit_id ?? null,
+    is_outdated: positionIsNull ? 1 : 0,
+    original_line_start:
+      apiRow.original_start_line ?? apiRow.original_line ?? null,
+    original_line_end: apiRow.original_line ?? null,
+    original_commit_sha: apiRow.original_commit_id ?? null,
+    body: apiRow.body ?? '',
+    external_created_at: apiRow.created_at ?? null,
+  };
+}
+
+module.exports = {
+  name,
+  credentialEnvVar,
+  resolveCredentials,
+  fetchComments,
+  mapComment,
+};

package/src/external/index.js

@@ -0,0 +1,37 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+/**
+ * External comment source dispatcher.
+ *
+ * Each external source (currently GitHub; GitLab/Linear planned) ships a
+ * sibling adapter module that exports `{ name, fetchComments, mapComment }`.
+ * This file maintains the keyed registry and resolves a `source` string to
+ * the matching adapter. Adding a new source is a one-file change here plus
+ * the new adapter module — no routes or repositories need to know.
+ */
+
+const githubAdapter = require('./github-adapter');
+
+const adapters = {
+  [githubAdapter.name]: githubAdapter,
+};
+
+/**
+ * Look up an adapter by its `source` string.
+ *
+ * @param {string} source - e.g. 'github'
+ * @returns {{ name: string, fetchComments: Function, mapComment: Function }}
+ * @throws {Error} when no adapter is registered for the source name
+ */
+function getAdapter(source) {
+  // Own-property guard: `adapters` is a plain object, so `adapters['toString']`
+  // would resolve to Object.prototype.toString (a function) and the route's
+  // unknown-source check (which depends on this function throwing) would
+  // silently pass. Use hasOwnProperty so only registered adapters resolve.
+  if (typeof source !== 'string' || !Object.prototype.hasOwnProperty.call(adapters, source)) {
+    throw new Error(`Unknown external comment source: ${source}`);
+  }
+  return adapters[source];
+}
+
+module.exports = { getAdapter, adapters };

package/src/github/client.js

@@ -158,6 +158,48 @@ class GitHubClient {
     }
   }
 
+  /**
+   * Fetch all inline (line-anchored) review comments on a pull request.
+   *
+   * Uses the GitHub REST API `pulls.listReviewComments` endpoint and paginates
+   * automatically via `octokit.paginate` to handle PRs with more than 100
+   * comments. Returns the raw API objects unchanged — mapping to local rows
+   * happens in the adapter / route layer (keeps this client thin and testable).
+   *
+   * Note: this endpoint returns inline review comments only. Issue-level (PR
+   * conversation tab) comments come from a different endpoint and are not
+   * included here.
+   *
+   * @param {Object} params
+   * @param {string} params.owner - Repository owner
+   * @param {string} params.repo - Repository name
+   * @param {number} params.pull_number - Pull request number
+   * @returns {Promise<Array<Object>>} Raw review-comment objects with fields
+   *   such as `id`, `pull_request_review_id`, `in_reply_to_id`, `body`,
+   *   `user`, `path`, `commit_id`, `original_commit_id`, `position`,
+   *   `original_position`, `line`, `start_line`, `original_line`,
+   *   `original_start_line`, `side`, `start_side`, `html_url`, `created_at`,
+   *   `updated_at`.
+   * @throws {GitHubApiError} 404 when the PR is not found, 429 on rate limit,
+   *   503 on network failure, or a wrapped error for other API failures.
+   */
+  async listReviewComments({ owner, repo, pull_number }) {
+    try {
+      const comments = await this.octokit.paginate(
+        this.octokit.rest.pulls.listReviewComments,
+        {
+          owner,
+          repo,
+          pull_number,
+          per_page: 100
+        }
+      );
+      return comments;
+    } catch (error) {
+      await this.handleApiError(error, owner, repo, pull_number);
+    }
+  }
+
   /**
    * Validate GitHub token by making a test API call
    * @returns {Promise<boolean>} Whether the token is valid
@@ -209,7 +251,8 @@ class GitHubClient {
       console.error('GitHub API error:', error);
     }
 
-    // Handle rate limiting with exponential backoff
+    // Handle rate limiting with exponential backoff (primary rate limit:
+    // `x-ratelimit-remaining: 0`).
     if (error.status === 403 && error.response?.headers?.['x-ratelimit-remaining'] === '0') {
       const resetTime = parseInt(error.response.headers['x-ratelimit-reset']) * 1000;
       const waitTime = Math.max(resetTime - Date.now(), 1000);
@@ -219,6 +262,39 @@ class GitHubClient {
       throw new GitHubApiError(`GitHub API rate limit exceeded. Retrying in ${Math.ceil(waitTime / 1000)} seconds...`, 429);
     }
 
+    // Secondary rate limits ("abuse detection") return 403 WITHOUT the
+    // standard rate-limit headers. They're signaled either by a `retry-after`
+    // header or by message text mentioning "secondary rate limit", "abuse",
+    // or "rate limit". Without this branch they'd fall through to the
+    // permission-failure path and the user would be told their token is
+    // missing scopes — misleading.
+    if (error.status === 403) {
+      const retryAfterHeader = error.response?.headers?.['retry-after'];
+      const messageText = String(error.message || '');
+      const looksLikeRateLimit =
+        retryAfterHeader != null ||
+        /secondary rate limit/i.test(messageText) ||
+        /abuse/i.test(messageText) ||
+        /rate limit/i.test(messageText);
+
+      if (looksLikeRateLimit) {
+        const retryAfterSec = retryAfterHeader != null ? parseInt(retryAfterHeader, 10) : null;
+        const suffix = Number.isFinite(retryAfterSec) && retryAfterSec > 0
+          ? ` Retry after ${retryAfterSec} seconds.`
+          : '';
+        throw new GitHubApiError(`GitHub API rate limit exceeded (secondary rate limit).${suffix}`, 429);
+      }
+
+      // Genuine permission / scope failure. Without this branch the error
+      // would fall through to the generic plain-`Error` path and route
+      // handlers would map it to a 500 instead of a 403, hiding the real
+      // cause from the reviewer.
+      throw new GitHubApiError(
+        `Insufficient permissions for ${owner}/${repo}. Your GitHub token may be missing required scopes.`,
+        403
+      );
+    }
+
     // Handle authentication errors
     if (error.status === 401) {
       throw new GitHubApiError('GitHub authentication failed. Check your token in ~/.pair-review/config.json', 401);

package/src/routes/config.js

@@ -35,6 +35,32 @@ const router = express.Router();
 // information (the next notifier will re-populate it).
 let pendingUpdateVersion = null;
 
+/**
+ * Runtime configuration script
+ *
+ * Returns a tiny JS file that sets `window.PAIR_REVIEW_RUNTIME_CONFIG`
+ * synchronously, plus an `external-comments-disabled` class on
+ * `documentElement` when the feature is off. Loaded via a `<script>` tag
+ * BEFORE the main app JS so components like AIPanel can check the flag
+ * at construction time (avoids FOUC of UI elements that should be hidden).
+ *
+ * No-store so each page load reflects current config without restart.
+ */
+router.get('/runtime-config.js', (req, res) => {
+  const config = req.app.get('config') || {};
+  const externalCommentsEnabled = config.external_comments !== false;
+  const runtimeConfig = { external_comments_enabled: externalCommentsEnabled };
+  const body = [
+    `window.PAIR_REVIEW_RUNTIME_CONFIG = ${JSON.stringify(runtimeConfig)};`,
+    `if (!window.PAIR_REVIEW_RUNTIME_CONFIG.external_comments_enabled) {`,
+    `  document.documentElement.classList.add('external-comments-disabled');`,
+    `}`,
+  ].join('\n');
+  res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+  res.send(body);
+});
+
 /**
  * Get user configuration (for frontend use)
  * Returns safe-to-expose configuration values
@@ -65,6 +91,7 @@ router.get('/api/config', (req, res) => {
     pi_available: getCachedAvailability('pi')?.available || false,
     assisted_by_url: config.assisted_by_url || 'https://github.com/in-the-loop-labs/pair-review',
     enable_graphite: config.enable_graphite === true,
+    external_comments: config.external_comments !== false,
     chat_spinner: config.chat_spinner || 'dots',
     // Share configuration for external review viewers.
     // - url: The base URL of the external share site