@in-the-loop-labs/pair-review 3.1.4 → 3.2.0

package/src/git/base-branch.js

@@ -1,12 +1,9 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const { execSync } = require('child_process');
-const { readFileSync } = require('fs');
-const path = require('path');
 const logger = require('../utils/logger');
 
 const defaults = {
   execSync,
-  readFileSync,
   // Callers should pass a resolved token via _deps.getGitHubToken.
   // This default returns empty so GitHub lookup is silently skipped
   // when no token is provided — never re-resolve config internally.
@@ -135,53 +132,6 @@ function buildStack(state, currentBranch, trunk) {
   return entries;
 }
 
-/**
- * Read Graphite PR info from the `.graphite_pr_info` file in the git dir.
- *
- * @param {string} repoPath - Absolute path to the repository
- * @param {Object} deps - Dependencies (execSync, readFileSync)
- * @returns {Object|null} Parsed PR info object with `prInfos` array, or null
- */
-function readGraphitePRInfo(repoPath, deps) {
-  try {
-    const gitCommonDir = deps.execSync('git rev-parse --git-common-dir', {
-      cwd: repoPath,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-
-    const prInfoPath = path.resolve(repoPath, gitCommonDir, '.graphite_pr_info');
-    const raw = deps.readFileSync(prInfoPath, 'utf8');
-    return JSON.parse(raw);
-  } catch (error) {
-    logger.debug(`Graphite PR info read failed: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Enrich stack entries with PR numbers from Graphite PR info.
- *
- * @param {Array} stack - Stack entries from buildStack
- * @param {Array} prInfos - Array of PR info objects with headRefName and prNumber
- * @returns {Array} New array of stack entries, each with optional prNumber
- */
-function enrichStackWithPRInfo(stack, prInfos) {
-  if (!prInfos || !Array.isArray(prInfos)) return stack;
-
-  const prMap = new Map();
-  for (const info of prInfos) {
-    if (info.headRefName) {
-      prMap.set(info.headRefName, info.prNumber);
-    }
-  }
-
-  return stack.map(entry => {
-    const prNumber = prMap.get(entry.branch);
-    return prNumber != null ? { ...entry, prNumber } : { ...entry };
-  });
-}
-
 /**
  * Try GitHub API to find an open PR for this branch.
  */
@@ -302,4 +252,4 @@ function getDefaultBranch(localPath, _deps) {
   return null;
 }
 
-module.exports = { detectBaseBranch, getDefaultBranch, tryGraphiteState, buildStack, readGraphitePRInfo, enrichStackWithPRInfo };
+module.exports = { detectBaseBranch, getDefaultBranch, tryGraphiteState, buildStack };

package/src/git/worktree-lock.js

@@ -0,0 +1,88 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * In-memory worktree lock manager.
+ *
+ * Prevents concurrent git operations on the same worktree during
+ * stack analysis. Non-blocking — callers check and fail fast.
+ */
+
+const logger = require('../utils/logger');
+
+class WorktreeLockManager {
+  constructor() {
+    /** @type {Map<string, { holderId: string, lockedAt: Date }>} */
+    this._locks = new Map();
+  }
+
+  /**
+   * Acquire a lock on a worktree path.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {string} holderId - Unique identifier for the lock holder (e.g. stackAnalysisId)
+   * @returns {boolean} true if acquired (or re-acquired by same holder), false if held by another
+   */
+  acquire(worktreePath, holderId) {
+    const existing = this._locks.get(worktreePath);
+
+    if (existing) {
+      if (existing.holderId === holderId) {
+        // Re-acquire by same holder — update timestamp
+        existing.lockedAt = new Date();
+        logger.debug(`Worktree lock re-acquired: ${worktreePath} by ${holderId}`);
+        return true;
+      }
+      logger.debug(`Worktree lock denied: ${worktreePath} held by ${existing.holderId}, requested by ${holderId}`);
+      return false;
+    }
+
+    this._locks.set(worktreePath, { holderId, lockedAt: new Date() });
+    logger.info(`Worktree lock acquired: ${worktreePath} by ${holderId}`);
+    return true;
+  }
+
+  /**
+   * Release a lock on a worktree path.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {string} holderId - Must match the holder that acquired the lock
+   * @returns {boolean} true if released, false if not held or held by a different holder
+   */
+  release(worktreePath, holderId) {
+    const existing = this._locks.get(worktreePath);
+
+    if (!existing) {
+      logger.debug(`Worktree lock release: no lock found for ${worktreePath}`);
+      return false;
+    }
+
+    if (existing.holderId !== holderId) {
+      logger.debug(`Worktree lock release denied: ${worktreePath} held by ${existing.holderId}, release requested by ${holderId}`);
+      return false;
+    }
+
+    this._locks.delete(worktreePath);
+    logger.info(`Worktree lock released: ${worktreePath} by ${holderId}`);
+    return true;
+  }
+
+  /**
+   * Check whether a worktree is currently locked.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @returns {{ locked: boolean, holderId?: string }}
+   */
+  isLocked(worktreePath) {
+    const existing = this._locks.get(worktreePath);
+
+    if (!existing) {
+      return { locked: false };
+    }
+
+    return { locked: true, holderId: existing.holderId };
+  }
+}
+
+// Singleton instance for application-wide use
+const worktreeLock = new WorktreeLockManager();
+
+module.exports = { worktreeLock, WorktreeLockManager };

package/src/git/worktree.js

@@ -30,6 +30,15 @@ class GitWorktreeManager {
     this.worktreeRepo = db ? new WorktreeRepository(db) : null;
   }
 
+  /**
+   * Create a simple-git instance for a path. Extracted for testability.
+   * @param {string} dirPath
+   * @returns {import('simple-git').SimpleGit}
+   */
+  _gitFor(dirPath) {
+    return simpleGit(dirPath);
+  }
+
   /**
    * Apply the name template to generate a worktree directory name
    * @param {Object} context - Template context variables
@@ -902,6 +911,61 @@ class GitWorktreeManager {
     }
   }
 
+  /**
+   * Checkout a different PR branch in an existing worktree.
+   *
+   * Used by stack analysis to switch the shared worktree between PRs.
+   * Stores a persistent ref (refs/remotes/<remote>/pr-<N>) instead of
+   * overwriting FETCH_HEAD, so multiple PR heads can coexist.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {number} prNumber - PR number to checkout
+   * @param {Object} [options={}]
+   * @param {string} [options.remote='origin'] - Git remote name (overridden by resolveRemoteForPR if prData provided)
+   * @param {Object} [options.prData=null] - PR data from GitHub API (for fork remote resolution)
+   * @param {Object} [options.prInfo=null] - PR info { owner, repo, number } (for fork remote resolution)
+   * @returns {Promise<string>} The HEAD SHA after checkout
+   * @throws {Error} If the worktree has uncommitted changes
+   */
+  async checkoutBranch(worktreePath, prNumber, options = {}) {
+    const { remote: defaultRemote = 'origin', prData = null, prInfo = null } = options;
+
+    try {
+      // 1. Reject if worktree has uncommitted changes
+      const hasChanges = await this.hasLocalChanges(worktreePath);
+      if (hasChanges) {
+        throw new Error(`Worktree has uncommitted changes. Cannot checkout PR #${prNumber} at: ${worktreePath}`);
+      }
+
+      const git = this._gitFor(worktreePath);
+
+      // 2. Resolve the correct remote (handles fork PRs)
+      const remote = (prData || prInfo)
+        ? await this.resolveRemoteForPR(git, prData, prInfo)
+        : defaultRemote;
+
+      // 3. Fetch PR head into a persistent ref
+      console.log(`Fetching PR #${prNumber} head from ${remote} into refs/remotes/${remote}/pr-${prNumber}...`);
+      await git.fetch([remote, `+refs/pull/${prNumber}/head:refs/remotes/${remote}/pr-${prNumber}`]);
+
+      // 4. Reset worktree to the fetched ref
+      console.log(`Resetting worktree to refs/remotes/${remote}/pr-${prNumber}...`);
+      await git.raw(['reset', '--hard', `refs/remotes/${remote}/pr-${prNumber}`]);
+
+      // 5. Return the new HEAD SHA
+      const headSha = (await git.revparse(['HEAD'])).trim();
+      console.log(`Worktree checked out PR #${prNumber} at ${headSha}`);
+      return headSha;
+
+    } catch (error) {
+      if (error.message.includes('uncommitted changes')) {
+        throw error;
+      }
+      console.error(`Error checking out PR #${prNumber}:`, error);
+      throw new Error(`Failed to checkout PR #${prNumber}: ${error.message}`);
+    }
+  }
+
   /**
    * Cleanup stale worktrees that haven't been accessed within the retention period
    * @param {number} retentionDays - Number of days to retain worktrees (default: 7)

package/src/github/stack-walker.js

@@ -0,0 +1,196 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../utils/logger');
+
+const DEFAULT_TRUNK_BRANCHES = ['main', 'master', 'develop'];
+const MAX_WALK_DEPTH = 20;
+
+const FETCH_PR_QUERY = `
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        number title baseRefName headRefName headRefOid state url
+      }
+    }
+  }
+`;
+
+const FIND_PRS_BY_HEAD_QUERY = `
+  query($owner: String!, $repo: String!, $branch: String!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequests(headRefName: $branch, states: [OPEN, MERGED], first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
+        nodes { number title baseRefName headRefName headRefOid state url }
+      }
+    }
+  }
+`;
+
+const FIND_PRS_BY_BASE_QUERY = `
+  query($owner: String!, $repo: String!, $branch: String!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequests(baseRefName: $branch, states: [OPEN], first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
+        nodes { number title baseRefName headRefName headRefOid state url }
+      }
+    }
+  }
+`;
+
+/**
+ * Select the best PR from a list of candidates for the same branch.
+ * Prefers OPEN over MERGED.
+ *
+ * @param {Array} prs - Array of PR nodes from GraphQL
+ * @returns {Object|null} The best candidate or null
+ */
+function pickBestPR(prs) {
+  if (!prs || prs.length === 0) return null;
+  const open = prs.find(pr => pr.state === 'OPEN');
+  if (open) return open;
+  return prs[0];
+}
+
+/**
+ * Walk a GitHub PR stack by following the branch chain via GraphQL.
+ *
+ * Starting from a given PR, walks up toward trunk (following baseRefName)
+ * and down toward the tip (following headRefName) to discover the full stack.
+ *
+ * @param {Object} client - GitHubClient instance (uses client.octokit.graphql)
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} prNumber - Starting PR number
+ * @param {Object} [_deps] - Optional dependency overrides for testing
+ * @param {string[]} [_deps.defaultBranches] - Branch names considered trunk
+ * @returns {Promise<Array>} Ordered stack from trunk to tip
+ */
+async function walkPRStack(client, owner, repo, prNumber, _deps) {
+  const deps = { defaultBranches: DEFAULT_TRUNK_BRANCHES, ..._deps };
+  const graphql = client.octokit.graphql.bind(client.octokit);
+  const visited = new Set();
+
+  // Step 1: Fetch the starting PR
+  const startResult = await graphql(FETCH_PR_QUERY, { owner, repo, number: prNumber });
+  const startPR = startResult.repository?.pullRequest;
+  if (!startPR) {
+    throw new Error(`PR #${prNumber} not found in ${owner}/${repo}`);
+  }
+
+  logger.debug(`Stack walker: starting from PR #${startPR.number} (${startPR.headRefName} -> ${startPR.baseRefName})`);
+  visited.add(startPR.headRefName);
+
+  // Step 2: Walk UP toward trunk
+  const parents = []; // will be reversed at the end
+  let currentBase = startPR.baseRefName;
+  let walkUpDepth = 0;
+
+  while (walkUpDepth < MAX_WALK_DEPTH) {
+    if (deps.defaultBranches.includes(currentBase)) {
+      // Reached trunk
+      break;
+    }
+    if (visited.has(currentBase)) {
+      logger.warn(`Stack walker: cycle detected at branch "${currentBase}", stopping upward walk`);
+      break;
+    }
+    visited.add(currentBase);
+
+    let parentPR;
+    try {
+      const result = await graphql(FIND_PRS_BY_HEAD_QUERY, { owner, repo, branch: currentBase });
+      const candidates = result.repository?.pullRequests?.nodes || [];
+      parentPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker: GraphQL error walking up at branch "${currentBase}": ${err.message}`);
+      break;
+    }
+
+    if (!parentPR) {
+      // No parent PR found — currentBase is effectively trunk for this stack
+      break;
+    }
+
+    parents.push({
+      branch: parentPR.headRefName,
+      isTrunk: false,
+      prNumber: parentPR.number,
+      title: parentPR.title,
+      state: parentPR.state,
+      url: parentPR.url,
+      headSha: parentPR.headRefOid,
+    });
+
+    currentBase = parentPR.baseRefName;
+    walkUpDepth++;
+  }
+
+  if (walkUpDepth >= MAX_WALK_DEPTH) {
+    logger.warn(`Stack walker: upward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  // The trunk entry is whatever branch the topmost PR targets
+  const trunkBranch = currentBase;
+
+  // Step 3: Walk DOWN toward tip
+  const children = [];
+  let currentHead = startPR.headRefName;
+  let walkDownDepth = 0;
+
+  while (walkDownDepth < MAX_WALK_DEPTH) {
+    let childPR;
+    try {
+      const result = await graphql(FIND_PRS_BY_BASE_QUERY, { owner, repo, branch: currentHead });
+      const candidates = result.repository?.pullRequests?.nodes || [];
+      childPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker: GraphQL error walking down at branch "${currentHead}": ${err.message}`);
+      break;
+    }
+
+    if (!childPR) {
+      break;
+    }
+
+    if (visited.has(childPR.headRefName)) {
+      logger.warn(`Stack walker: cycle detected at branch "${childPR.headRefName}", stopping downward walk`);
+      break;
+    }
+    visited.add(childPR.headRefName);
+
+    children.push({
+      branch: childPR.headRefName,
+      isTrunk: false,
+      prNumber: childPR.number,
+      title: childPR.title,
+      state: childPR.state,
+      url: childPR.url,
+      headSha: childPR.headRefOid,
+    });
+
+    currentHead = childPR.headRefName;
+    walkDownDepth++;
+  }
+
+  if (walkDownDepth >= MAX_WALK_DEPTH) {
+    logger.warn(`Stack walker: downward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  // Step 4: Assemble the ordered stack (trunk -> ... -> parents -> start -> children -> ... -> tip)
+  const stack = [
+    { branch: trunkBranch, isTrunk: true },
+    ...parents.reverse(),
+    {
+      branch: startPR.headRefName,
+      isTrunk: false,
+      prNumber: startPR.number,
+      title: startPR.title,
+      state: startPR.state,
+      url: startPR.url,
+      headSha: startPR.headRefOid,
+    },
+    ...children,
+  ];
+
+  logger.debug(`Stack walker: found ${stack.length} entries (${stack.filter(e => !e.isTrunk).length} PRs)`);
+  return stack;
+}
+
+module.exports = { walkPRStack, DEFAULT_TRUNK_BRANCHES };

package/src/routes/local.js

@@ -16,7 +16,7 @@ const express = require('express');
 const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs').promises;
-const { queryOne, run, ReviewRepository, RepoSettingsRepository, AnalysisRunRepository, CouncilRepository } = require('../database');
+const { query, queryOne, run, ReviewRepository, RepoSettingsRepository, AnalysisRunRepository, CouncilRepository } = require('../database');
 const Analyzer = require('../ai/analyzer');
 const { v4: uuidv4 } = require('uuid');
 const logger = require('../utils/logger');
@@ -32,8 +32,7 @@ const { getShaAbbrevLength } = require('../git/sha-abbrev');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 const { getProviderClass, createProvider } = require('../ai/provider');
-const { readFileSync } = require('fs');
-const { getDefaultBranch, tryGraphiteState, readGraphitePRInfo, enrichStackWithPRInfo } = require('../git/base-branch');
+const { getDefaultBranch, tryGraphiteState } = require('../git/base-branch');
 const { CommentRepository } = require('../database');
 const { runExecutableAnalysis, getChangedFiles } = require('./executable-analysis');
 const {
@@ -630,12 +629,17 @@ router.get('/api/local/:reviewId', async (req, res) => {
     const localConfig = req.app.get('config') || {};
     if (localConfig.enable_graphite === true && review.local_path && branchName && branchName !== 'unknown' && branchName !== 'HEAD') {
       try {
-        const graphiteResult = tryGraphiteState(review.local_path, branchName, { execSync, readFileSync });
+        const graphiteResult = tryGraphiteState(review.local_path, branchName, { execSync });
         if (graphiteResult?.stack) {
-          const prInfo = readGraphitePRInfo(review.local_path, { execSync, readFileSync });
-          stackData = prInfo?.prInfos
-            ? enrichStackWithPRInfo(graphiteResult.stack, prInfo.prInfos)
-            : graphiteResult.stack;
+          // Enrich with PR numbers from pr_metadata DB
+          const allPRs = repositoryName
+            ? await query(db, 'SELECT pr_number, head_branch FROM pr_metadata WHERE repository = ? COLLATE NOCASE', [repositoryName])
+            : [];
+          const prMap = new Map(allPRs.filter(p => p.head_branch).map(p => [p.head_branch, p.pr_number]));
+          stackData = graphiteResult.stack.map(entry => {
+            const prNumber = prMap.get(entry.branch);
+            return prNumber != null ? { ...entry, prNumber } : entry;
+          });
         }
       } catch {
         // Non-fatal — stack detection is an enhancement