@in-the-loop-labs/pair-review 3.6.0 → 3.7.0

package/src/github/errors.js

@@ -0,0 +1,55 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Custom error class for GitHub API errors that preserves the HTTP status code.
+ * Route handlers can check `error.status` or use `instanceof GitHubApiError`
+ * instead of fragile string matching on error messages.
+ */
+class GitHubApiError extends Error {
+  /**
+   * @param {string} message - Human-readable error message
+   * @param {number} status - HTTP status code (e.g. 401, 403, 404, 429)
+   */
+  constructor(message, status) {
+    super(message);
+    this.name = 'GitHubApiError';
+    this.status = status;
+  }
+}
+
+/**
+ * Detect whether a GraphQL error is a complexity/cost limit error from GitHub.
+ * These errors mean the mutation was too large and can be retried with fewer items.
+ *
+ * @param {Error} error - The error thrown by octokit.graphql
+ * @returns {boolean} True if the error is a complexity/cost limit error
+ */
+function isComplexityError(error) {
+  const patterns = [
+    /complexity/i,
+    /MAX_NODE_LIMIT/,
+    /cost exceeds/i,
+    /too large/i,
+    /query size exceeds/i,
+  ];
+
+  if (error.message) {
+    for (const pattern of patterns) {
+      if (pattern.test(error.message)) return true;
+    }
+  }
+
+  if (error.errors && Array.isArray(error.errors)) {
+    for (const err of error.errors) {
+      if (err.message) {
+        for (const pattern of patterns) {
+          if (pattern.test(err.message)) return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+module.exports = { GitHubApiError, isComplexityError };

package/src/github/impl/graphql/pending-review-comments.js

@@ -0,0 +1,230 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../../../utils/logger');
+const { isComplexityError } = require('../../errors');
+
+/**
+ * GraphQL implementation of the pending-review-comments area.
+ *
+ * Adds inline comments (line-level, range-level, and file-level) to an
+ * already-pending review. Uses the `addPullRequestReviewThread` mutation
+ * batched together for throughput, with adaptive batch sizing that halves
+ * on GitHub complexity errors.
+ *
+ * The return shape (success count, failed flag, failedDetails) is the
+ * same shape `GitHubClient.addCommentsInBatches` historically returned;
+ * callers depend on that exact shape for cleanup and error reporting.
+ */
+
+const MIN_BATCH_SIZE = 1;
+const DEFAULT_BATCH_SIZE = 10;
+
+/**
+ * Build the GraphQL mutation text for a batch of comments. Aliases each
+ * inner mutation as `comment0`, `comment1`, ... so partial-failure paths
+ * can map errors back to individual comments via `error.path[0]`.
+ *
+ * @param {Array} batch - Slice of comments to include in this mutation
+ * @returns {string} The full mutation text
+ */
+function buildBatchMutation(batch) {
+  const commentMutations = batch.map((comment, index) => {
+    const isFileLevel = comment.isFileLevel || !comment.line;
+
+    if (isFileLevel) {
+      return `
+          comment${index}: addPullRequestReviewThread(input: {
+            pullRequestId: $prId
+            pullRequestReviewId: $reviewId
+            path: ${JSON.stringify(comment.path)}
+            subjectType: FILE
+            body: ${JSON.stringify(comment.body)}
+          }) {
+            thread { id }
+          }
+        `;
+    }
+
+    const side = comment.side || 'RIGHT';
+    const startLineField = comment.start_line ? `startLine: ${comment.start_line}\n                ` : '';
+    return `
+          comment${index}: addPullRequestReviewThread(input: {
+            pullRequestId: $prId
+            pullRequestReviewId: $reviewId
+            path: ${JSON.stringify(comment.path)}
+            ${startLineField}line: ${comment.line}
+            side: ${side}
+            body: ${JSON.stringify(comment.body)}
+          }) {
+            thread { id }
+          }
+        `;
+  }).join('\n');
+
+  return `
+      mutation AddReviewComments($prId: ID!, $reviewId: ID!) {
+        ${commentMutations}
+      }
+    `;
+}
+
+/**
+ * Add comments to a pending review in batches, with adaptive batch sizing
+ * on GitHub complexity errors. Sequential, with one retry per batch.
+ *
+ * @param {Object} octokit - Octokit instance (must expose .graphql)
+ * @param {string} prNodeId - GraphQL node ID for the PR
+ * @param {string} reviewId - GraphQL node ID for the pending review
+ * @param {Array} comments - Array of comments with path, line (optional), side, body, isFileLevel
+ * @param {number} [batchSize=10] - Initial batch size
+ * @returns {Promise<{successCount: number, failed: boolean, failedDetails: string[]}>}
+ */
+async function addCommentsInBatches(octokit, prNodeId, reviewId, comments, batchSize = DEFAULT_BATCH_SIZE) {
+  if (comments.length === 0) {
+    return { successCount: 0, failed: false, failedDetails: [] };
+  }
+
+  let currentBatchSize = batchSize;
+  let remaining = comments.slice();
+  let totalSuccessful = 0;
+  const failedDetails = [];
+  let batchNumber = 0;
+
+  logger.info(`Adding ${comments.length} comments in batches of up to ${currentBatchSize}`);
+
+  while (remaining.length > 0) {
+    batchNumber++;
+    const batch = remaining.slice(0, currentBatchSize);
+    logger.info(`Adding comments batch ${batchNumber} (${batch.length} comments, ${remaining.length} remaining)...`);
+
+    const batchMutation = buildBatchMutation(batch);
+
+    // Try the batch, with one retry on failure
+    let batchResult = null;
+    let batchError = null;
+    let retryAttempt = 0;
+    const maxRetries = 1;
+    let reducedBatchSize = false;
+
+    while (retryAttempt <= maxRetries) {
+      try {
+        batchResult = await octokit.graphql(batchMutation, {
+          prId: prNodeId,
+          reviewId
+        });
+        batchError = null;
+        break;
+      } catch (error) {
+        batchError = error;
+
+        // Complexity/cost limit: halve batch size and re-attempt
+        if (isComplexityError(error)) {
+          const newSize = Math.max(MIN_BATCH_SIZE, Math.floor(currentBatchSize / 2));
+          if (newSize < currentBatchSize) {
+            logger.warn(
+              `Batch ${batchNumber} hit complexity limit (size ${currentBatchSize}), ` +
+              `reducing batch size to ${newSize}`
+            );
+            currentBatchSize = newSize;
+            reducedBatchSize = true;
+            break;
+          }
+          // Already at the minimum - fall through to normal retry logic
+        }
+
+        if (retryAttempt < maxRetries) {
+          logger.warn(`Batch ${batchNumber} failed, retrying... (${error.message})`);
+          retryAttempt++;
+          // Fixed 1-second delay before a single retry. Backoff has no benefit
+          // with maxRetries=1; either it works on retry or we clean up.
+          await new Promise(resolve => setTimeout(resolve, 1000));
+        } else {
+          logger.error(`Batch ${batchNumber} failed after retry: ${error.message}`);
+          break;
+        }
+      }
+    }
+
+    if (reducedBatchSize) {
+      // Re-attempt the same remaining slice with the smaller batch size.
+      continue;
+    }
+
+    if (batchError) {
+      // Build a map of per-comment errors from the GraphQL errors array.
+      // Each GraphQL error has a `path` like ["comment0"] that maps to the
+      // mutation alias, letting us match errors to specific comments.
+      const perCommentErrors = {};
+      if (batchError.errors && Array.isArray(batchError.errors)) {
+        for (const err of batchError.errors) {
+          if (err.path && err.path.length > 0) {
+            const alias = err.path[0];
+            perCommentErrors[alias] = err.message || 'Unknown error';
+          }
+        }
+      }
+
+      if (batchError.data) {
+        logger.warn(`GraphQL returned partial results with errors: ${JSON.stringify(batchError.errors || batchError.message)}`);
+        let batchSuccessful = 0;
+        for (let i = 0; i < batch.length; i++) {
+          const commentResult = batchError.data[`comment${i}`];
+          if (commentResult && commentResult.thread && commentResult.thread.id) {
+            batchSuccessful++;
+          } else {
+            const ghError = perCommentErrors[`comment${i}`] || 'No error details available';
+            const location = `${batch[i].path}:${batch[i].line || 'file-level'}`;
+            logger.warn(`Comment ${i} in batch ${batchNumber} failed to add: ${location} - ${ghError}`);
+            failedDetails.push(`${location} - ${ghError}`);
+          }
+        }
+        if (batchSuccessful < batch.length) {
+          logger.error(`CRITICAL: Batch ${batchNumber} had ${batch.length - batchSuccessful} failures`);
+          return { successCount: totalSuccessful + batchSuccessful, failed: true, failedDetails };
+        }
+        logger.info(`Batch ${batchNumber} complete (recovered from partial error): ${batchSuccessful} comments added`);
+        totalSuccessful += batchSuccessful;
+      } else {
+        const totalError = batchError.message || 'Unknown error';
+        logger.error(`CRITICAL: Batch ${batchNumber} failed completely: ${totalError}`);
+        for (let i = 0; i < batch.length; i++) {
+          const ghError = perCommentErrors[`comment${i}`] || totalError;
+          const location = `${batch[i].path}:${batch[i].line || 'file-level'}`;
+          failedDetails.push(`${location} - ${ghError}`);
+        }
+        return { successCount: totalSuccessful, failed: true, failedDetails };
+      }
+    } else if (batchResult) {
+      let batchSuccessful = 0;
+      for (let i = 0; i < batch.length; i++) {
+        const commentResult = batchResult[`comment${i}`];
+        if (commentResult && commentResult.thread && commentResult.thread.id) {
+          batchSuccessful++;
+        } else {
+          const location = `${batch[i].path}:${batch[i].line || 'file-level'}`;
+          logger.warn(`Comment ${i} in batch ${batchNumber} failed to add: ${location} - No error details available`);
+          failedDetails.push(`${location} - No error details available`);
+        }
+      }
+
+      if (batchSuccessful < batch.length) {
+        logger.error(`CRITICAL: Batch ${batchNumber} had ${batch.length - batchSuccessful} failures`);
+        return { successCount: totalSuccessful + batchSuccessful, failed: true, failedDetails };
+      }
+
+      totalSuccessful += batchSuccessful;
+      logger.info(`Batch ${batchNumber} complete: ${batchSuccessful} comments added`);
+    }
+
+    remaining = remaining.slice(batch.length);
+  }
+
+  logger.info(`All batches complete: ${totalSuccessful} total comments added`);
+  return { successCount: totalSuccessful, failed: false, failedDetails };
+}
+
+module.exports = {
+  addCommentsInBatches,
+  buildBatchMutation,
+  MIN_BATCH_SIZE,
+  DEFAULT_BATCH_SIZE
+};

package/src/github/impl/graphql/pending-review.js

@@ -0,0 +1,153 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../../../utils/logger');
+const { GitHubApiError } = require('../../errors');
+
+/**
+ * GraphQL implementation of the pending-review-check area.
+ *
+ * Provides:
+ *   - getPendingReviewForUser(owner, repo, prNumber)
+ *   - getReviewById(nodeId)
+ *
+ * Each function takes an Octokit-like client as its first parameter and
+ * returns the same shape `GitHubClient` historically returned.
+ */
+
+const PENDING_REVIEW_QUERY = `
+  query($owner: String!, $repo: String!, $prNumber: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $prNumber) {
+        reviews(states: PENDING, first: 1) {
+          nodes {
+            id
+            databaseId
+            body
+            url
+            state
+            createdAt
+            viewerDidAuthor
+            comments {
+              totalCount
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const REVIEW_BY_ID_QUERY = `
+  query($nodeId: ID!) {
+    node(id: $nodeId) {
+      ... on PullRequestReview {
+        id
+        state
+        submittedAt
+        url
+      }
+    }
+  }
+`;
+
+/**
+ * GitHub allows only ONE pending review per user per PR, so this returns
+ * either the single pending review or null if none exists.
+ *
+ * @param {Object} octokit - Octokit instance (must expose .graphql)
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} prNumber - Pull request number
+ * @returns {Promise<Object|null>} The pending review object or null
+ */
+async function getPendingReviewForUser(octokit, owner, repo, prNumber) {
+  try {
+    logger.debug(`Checking for pending review on PR #${prNumber} in ${owner}/${repo}`);
+
+    const result = await octokit.graphql(PENDING_REVIEW_QUERY, {
+      owner,
+      repo,
+      prNumber
+    });
+
+    const reviews = result.repository?.pullRequest?.reviews?.nodes || [];
+    const userPendingReview = reviews.find(review => review.viewerDidAuthor);
+
+    if (userPendingReview) {
+      logger.debug(`Found pending review for user: ${userPendingReview.id} with ${userPendingReview.comments.totalCount} comments`);
+      return {
+        id: userPendingReview.id,
+        databaseId: userPendingReview.databaseId,
+        body: userPendingReview.body,
+        url: userPendingReview.url,
+        state: userPendingReview.state,
+        createdAt: userPendingReview.createdAt,
+        comments: {
+          totalCount: userPendingReview.comments.totalCount
+        }
+      };
+    }
+
+    logger.debug('No pending review found for user');
+    return null;
+  } catch (error) {
+    logger.error(`Error checking for pending review: ${error.message}`);
+
+    if (error.status === 401) {
+      throw new GitHubApiError('GitHub authentication failed. Check your token in ~/.pair-review/config.json', 401);
+    }
+
+    if (error.status === 404 || error.errors?.some(e => e.type === 'NOT_FOUND')) {
+      throw new GitHubApiError(`Pull request #${prNumber} not found in repository ${owner}/${repo}`, 404);
+    }
+
+    if (error.errors) {
+      const messages = error.errors.map(e => e.message).join(', ');
+      throw new Error(`GitHub GraphQL error: ${messages}`);
+    }
+
+    throw new Error(`Failed to check for pending review: ${error.message}`);
+  }
+}
+
+/**
+ * Fetch a review by its GraphQL node ID.
+ *
+ * @param {Object} octokit - Octokit instance (must expose .graphql)
+ * @param {string} nodeId - GraphQL node ID for the review
+ * @returns {Promise<Object|null>} Review data or null if not found
+ */
+async function getReviewById(octokit, nodeId) {
+  try {
+    logger.debug(`Fetching review by node ID: ${nodeId}`);
+
+    const result = await octokit.graphql(REVIEW_BY_ID_QUERY, { nodeId });
+
+    if (!result.node || !result.node.id) {
+      logger.debug(`Review not found for node ID: ${nodeId}`);
+      return null;
+    }
+
+    const review = result.node;
+    logger.debug(`Found review ${nodeId}: state=${review.state}, submittedAt=${review.submittedAt}`);
+
+    return {
+      id: review.id,
+      state: review.state,
+      submittedAt: review.submittedAt,
+      url: review.url
+    };
+  } catch (error) {
+    if (error.errors?.some(e => e.type === 'NOT_FOUND' || e.message?.includes('not found'))) {
+      logger.debug(`Review not found for node ID: ${nodeId}`);
+      return null;
+    }
+
+    logger.warn(`Error fetching review by node ID ${nodeId}: ${error.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  getPendingReviewForUser,
+  getReviewById
+};

package/src/github/impl/graphql/review-lifecycle.js

@@ -0,0 +1,161 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../../../utils/logger');
+
+/**
+ * GraphQL implementation of the review-lifecycle area:
+ *   - addPullRequestReview (with or without body)
+ *   - submitPullRequestReview
+ *   - deletePullRequestReview
+ *
+ * Each function takes an Octokit-like client as its first parameter.
+ * Return shapes match what `GitHubClient` historically returned for these
+ * primitives so callers (notably the orchestration in `createReviewGraphQL`
+ * and `createDraftReviewGraphQL`) remain byte-identical.
+ */
+
+const ADD_REVIEW_MUTATION = `
+  mutation AddPendingReview($prId: ID!) {
+    addPullRequestReview(input: {
+      pullRequestId: $prId
+    }) {
+      pullRequestReview {
+        id
+        databaseId
+      }
+    }
+  }
+`;
+
+const ADD_REVIEW_WITH_BODY_MUTATION = `
+  mutation AddPendingReview($prId: ID!, $body: String) {
+    addPullRequestReview(input: {
+      pullRequestId: $prId
+      body: $body
+    }) {
+      pullRequestReview {
+        id
+        databaseId
+        url
+      }
+    }
+  }
+`;
+
+const SUBMIT_REVIEW_MUTATION = `
+  mutation SubmitReview($reviewId: ID!, $event: PullRequestReviewEvent!, $body: String) {
+    submitPullRequestReview(input: {
+      pullRequestReviewId: $reviewId
+      event: $event
+      body: $body
+    }) {
+      pullRequestReview {
+        id
+        databaseId
+        url
+        state
+      }
+    }
+  }
+`;
+
+const DELETE_REVIEW_MUTATION = `
+  mutation DeleteReview($reviewId: ID!) {
+    deletePullRequestReview(input: { pullRequestReviewId: $reviewId }) {
+      pullRequestReview { id }
+    }
+  }
+`;
+
+/**
+ * Create a pending review (no body). Used by the submit-review flow that
+ * passes the body later via `submitPullRequestReview`.
+ *
+ * Returns both the GraphQL node id (`id`) and the numeric database id
+ * (`databaseId`). The numeric id is required by the orchestration in
+ * `client.js` to address the same review via REST/host endpoints (e.g.
+ * the host `addCommentsInBatches` extension, which is path-shaped).
+ *
+ * @param {Object} octokit
+ * @param {string} prNodeId
+ * @returns {Promise<{id: string, databaseId: number|null}>}
+ */
+async function addPullRequestReview(octokit, prNodeId) {
+  const result = await octokit.graphql(ADD_REVIEW_MUTATION, { prId: prNodeId });
+  const review = result.addPullRequestReview.pullRequestReview;
+  return {
+    id: review.id,
+    databaseId: typeof review.databaseId === 'number' ? review.databaseId : null
+  };
+}
+
+/**
+ * Create a pending review with a body. Used by the draft-review flow which
+ * persists the summary on the pending review itself.
+ *
+ * @param {Object} octokit
+ * @param {string} prNodeId
+ * @param {string|null} body
+ * @returns {Promise<{id: string, databaseId: number|null, url: string}>}
+ */
+async function addPullRequestReviewWithBody(octokit, prNodeId, body) {
+  const result = await octokit.graphql(ADD_REVIEW_WITH_BODY_MUTATION, {
+    prId: prNodeId,
+    body: body || null
+  });
+  const review = result.addPullRequestReview.pullRequestReview;
+  return {
+    id: review.id,
+    databaseId: review.databaseId,
+    url: review.url
+  };
+}
+
+/**
+ * Submit a pending review with the chosen event (APPROVE/REQUEST_CHANGES/COMMENT).
+ *
+ * @param {Object} octokit
+ * @param {string} reviewId - GraphQL node ID of the pending review
+ * @param {string} event - APPROVE | REQUEST_CHANGES | COMMENT
+ * @param {string|null} body
+ * @returns {Promise<{id: string, databaseId: number|null, url: string, state: string}>}
+ */
+async function submitPullRequestReview(octokit, reviewId, event, body) {
+  const result = await octokit.graphql(SUBMIT_REVIEW_MUTATION, {
+    reviewId,
+    event,
+    body: body || null
+  });
+  const review = result.submitPullRequestReview.pullRequestReview;
+  return {
+    id: review.id,
+    databaseId: review.databaseId,
+    url: review.url,
+    state: review.state
+  };
+}
+
+/**
+ * Delete a pending review (cleanup on failure). Never throws; logs and
+ * returns false on failure.
+ *
+ * @param {Object} octokit
+ * @param {string} reviewId
+ * @returns {Promise<boolean>}
+ */
+async function deletePullRequestReview(octokit, reviewId) {
+  try {
+    await octokit.graphql(DELETE_REVIEW_MUTATION, { reviewId });
+    logger.info('Cleaned up pending review after failure');
+    return true;
+  } catch (cleanupError) {
+    logger.warn(`Failed to clean up pending review: ${cleanupError.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  addPullRequestReview,
+  addPullRequestReviewWithBody,
+  submitPullRequestReview,
+  deletePullRequestReview
+};