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

package/src/github/impl/rest/stack-walker.js

@@ -0,0 +1,309 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../../../utils/logger');
+
+/**
+ * REST implementation of the stack-walker area.
+ *
+ * Mirrors `impl/graphql/stack-walker.js` but uses REST endpoints:
+ *
+ *   - Q3 FETCH_PR_QUERY        -> `pulls.get({ owner, repo, pull_number })`
+ *   - Q4 FIND_PRS_BY_HEAD_QUERY -> `pulls.list({ owner, repo, head, state: 'all' })`
+ *   - Q5 FIND_PRS_BY_BASE_QUERY -> `pulls.list({ owner, repo, base, state: 'open' })`
+ *
+ * Returns the ordered stack shape `walkPRStack` historically returned
+ * (trunk -> parents (oldest first when reversed in caller) -> starting
+ * PR -> children). PR entries match the GraphQL impl's normalised node
+ * shape: { number, title, baseRefName, headRefName, headRefOid, state,
+ * url }, with `state` normalised to uppercase to match GraphQL
+ * semantics.
+ *
+ * Discovery scope: `findPRsByHead` passes `head: "${owner}:${branch}"`
+ * to `pulls.list`. GitHub REST's `head` filter is strictly
+ * `user:branch` and only matches PRs whose head ref lives on the same
+ * owner as the base repo; PRs opened from contributor forks are
+ * silently excluded. The GraphQL impl's `headRefName` filter has no
+ * such restriction.
+ *
+ * This impl is intended for alt-hosts (GitHub Enterprise, etc.) where
+ * stacking workflows do not involve forks. On github.com, `stack_walker`
+ * defaults to GraphQL (see `GRAPHQL_DEFAULT_AREAS` in `src/config.js`),
+ * where the fork restriction does not apply.
+ */
+
+const DEFAULT_TRUNK_BRANCHES = ['main', 'master', 'develop'];
+const MAX_WALK_DEPTH = 20;
+
+/**
+ * Normalise a REST PR object to the GraphQL-style shape used by the
+ * stack walker. REST exposes `state` in lowercase (`open`/`closed`) and
+ * separates `merged` via `merged_at != null`; GraphQL exposes
+ * `OPEN`/`CLOSED`/`MERGED` directly. Normalising here keeps the
+ * downstream walk logic transport-agnostic.
+ *
+ * @param {Object} pr - REST PR object (from `pulls.get` or `pulls.list`)
+ * @returns {Object} GraphQL-shaped PR node
+ */
+function normalisePR(pr) {
+  let state;
+  if (pr.merged_at) {
+    state = 'MERGED';
+  } else if (typeof pr.state === 'string') {
+    state = pr.state.toUpperCase();
+  } else {
+    state = 'OPEN';
+  }
+  return {
+    number: pr.number,
+    title: pr.title,
+    baseRefName: pr.base && pr.base.ref,
+    headRefName: pr.head && pr.head.ref,
+    headRefOid: pr.head && pr.head.sha,
+    state,
+    url: pr.html_url
+  };
+}
+
+/**
+ * Select the best PR from a list of candidates for the same branch.
+ * Prefers OPEN over MERGED. Mirrors the GraphQL impl exactly.
+ *
+ * @param {Array} prs - Array of normalised PR nodes
+ * @returns {Object|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];
+}
+
+/**
+ * Fetch the starting PR by number.
+ *
+ * @param {Object} octokit
+ * @param {string} owner
+ * @param {string} repo
+ * @param {number} prNumber
+ * @returns {Promise<Object|null>}
+ */
+async function fetchPR(octokit, owner, repo, prNumber) {
+  try {
+    const { data } = await octokit.rest.pulls.get({
+      owner,
+      repo,
+      pull_number: prNumber
+    });
+    return normalisePR(data);
+  } catch (err) {
+    if (err.status === 404) return null;
+    throw err;
+  }
+}
+
+/**
+ * Find PRs whose HEAD branch matches `branch`. Filters to OPEN + MERGED
+ * to match the GraphQL impl's `states: [OPEN, MERGED]`.
+ *
+ * Ordering note: GraphQL uses `orderBy: { field: UPDATED_AT, direction:
+ * DESC }`. The REST `pulls.list` endpoint sorts by `updated_at`
+ * descending by default; we pass it explicitly to stay
+ * observationally-identical.
+ *
+ * @param {Object} octokit
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} branch
+ * @returns {Promise<Array>}
+ */
+async function findPRsByHead(octokit, owner, repo, branch) {
+  // REST `state` filter accepts only `open|closed|all`. `closed`
+  // includes merged. We need OPEN + MERGED but not CLOSED-without-merge,
+  // so fetch with `state: 'all'` and filter client-side.
+  const { data } = await octokit.rest.pulls.list({
+    owner,
+    repo,
+    head: `${owner}:${branch}`,
+    state: 'all',
+    sort: 'updated',
+    direction: 'desc',
+    per_page: 5
+  });
+  return data
+    .map(normalisePR)
+    .filter(pr => pr.state === 'OPEN' || pr.state === 'MERGED');
+}
+
+/**
+ * Find PRs whose BASE branch matches `branch`. Mirrors GraphQL's
+ * `states: [OPEN]`.
+ *
+ * @param {Object} octokit
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} branch
+ * @returns {Promise<Array>}
+ */
+async function findPRsByBase(octokit, owner, repo, branch) {
+  const { data } = await octokit.rest.pulls.list({
+    owner,
+    repo,
+    base: branch,
+    state: 'open',
+    sort: 'updated',
+    direction: 'desc',
+    per_page: 5
+  });
+  return data.map(normalisePR);
+}
+
+/**
+ * Walk a PR stack using REST endpoints.
+ *
+ * Same algorithm as the GraphQL implementation; only the transport
+ * differs.
+ *
+ * @param {Object} octokit - Octokit instance bound to the host's baseUrl
+ * @param {string} owner
+ * @param {string} repo
+ * @param {number} prNumber
+ * @param {Object} [_deps]
+ * @param {string[]} [_deps.defaultBranches]
+ * @returns {Promise<Array>}
+ */
+async function walkPRStack(octokit, owner, repo, prNumber, _deps) {
+  const deps = { defaultBranches: DEFAULT_TRUNK_BRANCHES, ..._deps };
+  const visited = new Set();
+
+  // Step 1: Fetch the starting PR
+  const startPR = await fetchPR(octokit, owner, repo, prNumber);
+  if (!startPR) {
+    throw new Error(`PR #${prNumber} not found in ${owner}/${repo}`);
+  }
+
+  logger.debug(`Stack walker (REST): starting from PR #${startPR.number} (${startPR.headRefName} -> ${startPR.baseRefName})`);
+  visited.add(startPR.headRefName);
+
+  // Step 2: Walk UP toward trunk
+  const parents = [];
+  let currentBase = startPR.baseRefName;
+  let walkUpDepth = 0;
+
+  while (walkUpDepth < MAX_WALK_DEPTH) {
+    if (deps.defaultBranches.includes(currentBase)) {
+      break;
+    }
+    if (visited.has(currentBase)) {
+      logger.warn(`Stack walker (REST): cycle detected at branch "${currentBase}", stopping upward walk`);
+      break;
+    }
+    visited.add(currentBase);
+
+    let parentPR;
+    try {
+      const candidates = await findPRsByHead(octokit, owner, repo, currentBase);
+      parentPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker (REST): error walking up at branch "${currentBase}": ${err.message}`);
+      break;
+    }
+
+    if (!parentPR) {
+      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 (REST): upward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  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 candidates = await findPRsByBase(octokit, owner, repo, currentHead);
+      childPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker (REST): error walking down at branch "${currentHead}": ${err.message}`);
+      break;
+    }
+
+    if (!childPR) {
+      break;
+    }
+
+    if (visited.has(childPR.headRefName)) {
+      logger.warn(`Stack walker (REST): 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 (REST): downward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  // Step 4: Assemble the ordered stack
+  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 (REST): found ${stack.length} entries (${stack.filter(e => !e.isTrunk).length} PRs)`);
+  return stack;
+}
+
+module.exports = {
+  walkPRStack,
+  DEFAULT_TRUNK_BRANCHES,
+  MAX_WALK_DEPTH,
+  // Exposed for tests and parity verification.
+  _internals: {
+    normalisePR,
+    pickBestPR,
+    fetchPR,
+    findPRsByHead,
+    findPRsByBase
+  }
+};

package/src/github/operations/pending-review-comments.js

@@ -0,0 +1,79 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const graphqlImpl = require('../impl/graphql/pending-review-comments');
+const hostImpl = require('../impl/host/pending-review-comments');
+
+/**
+ * Dispatcher for the `pending_review_comments` area.
+ *
+ * Adds inline comments (line / range / file-level) to an already-pending
+ * review. This area is special: GitHub provides no REST equivalent for
+ * attaching comments to a pending draft, so the `"rest"` value is
+ * explicitly rejected at runtime per the plan. Alt-hosts must declare
+ * `"host"` and provide an extension endpoint.
+ *
+ * Dispatch:
+ *   - `"graphql"` (default for github.com): delegates to
+ *     `impl/graphql/pending-review-comments.js`. Identical behaviour to
+ *     `GitHubClient.addCommentsInBatches` prior to the Phase 3 refactor,
+ *     including the adaptive batch-size halving on complexity errors.
+ *   - `"rest"`: rejected with a clear error. GitHub REST cannot reliably
+ *     attach comments to a pending draft (see plan Hazards).
+ *   - `"host"`: delegates to `impl/host/pending-review-comments.js`,
+ *     which posts to the host's extension endpoint. Requires `prContext`
+ *     ({ owner, repo, prNumber }) because the host endpoint is
+ *     path-shaped — the GraphQL node IDs alone are not sufficient.
+ */
+
+const AREA = 'pending_review_comments';
+// Modes actually implemented by the dispatcher below. Co-located with the
+// dispatch logic so validateRepoConfig() and the dispatcher can't drift.
+// REST is intentionally excluded: GitHub REST cannot attach comments to a
+// pending draft review.
+const IMPLEMENTED_MODES = new Set(['graphql', 'host']);
+
+function selectFeature(features) {
+  return (features && features[AREA]) || 'graphql';
+}
+
+/**
+ * Add a list of comments to a pending review.
+ *
+ * The `prNodeId` / `reviewId` arguments are GraphQL-shaped (opaque node
+ * IDs) for the GraphQL path. For the `"host"` path, `prContext` supplies
+ * the path components and `reviewId` is interpreted as the host's review
+ * identifier (a REST id returned by the host's `review_lifecycle` impl).
+ *
+ * @param {Object} octokit - Octokit instance bound to the host's baseUrl
+ * @param {Object} features - Feature-flag object from the host binding
+ * @param {string} prNodeId - GraphQL node ID for the PR (graphql path)
+ * @param {string} reviewId - Review identifier. GraphQL node ID on the
+ *   graphql path; the host's REST review id on the host path.
+ * @param {Array} comments - Comments with path, line (optional), side, body, isFileLevel
+ * @param {number} [batchSize=10]
+ * @param {Object} [prContext] - `{ owner, repo, prNumber }`. Required for
+ *   the `"host"` path; ignored on the graphql path.
+ * @returns {Promise<{successCount: number, failed: boolean, failedDetails: string[]}>}
+ */
+async function addCommentsInBatches(octokit, features, prNodeId, reviewId, comments, batchSize, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.addCommentsInBatches(octokit, prNodeId, reviewId, comments, batchSize);
+  }
+  if (mode === 'rest') {
+    throw new Error(
+      'REST implementation for pending_review_comments is not supported: ' +
+      'GitHub REST cannot reliably attach comments to a pending draft review. ' +
+      'Use "graphql" for github.com or "host" with a host extension for alt-hosts.'
+    );
+  }
+  if (mode === 'host') {
+    return hostImpl.addCommentsInBatches(octokit, features, prContext, reviewId, comments, batchSize);
+  }
+  throw new Error(`Unknown features.pending_review_comments value: "${mode}"`);
+}
+
+module.exports = {
+  addCommentsInBatches,
+  AREA,
+  IMPLEMENTED_MODES
+};

package/src/github/operations/pending-review.js

@@ -0,0 +1,89 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const graphqlImpl = require('../impl/graphql/pending-review');
+const restImpl = require('../impl/rest/pending-review');
+
+/**
+ * Dispatcher for the `pending_review_check` area.
+ *
+ * Each operation inspects `features.pending_review_check`:
+ *   - `"graphql"` (default for github.com): delegates to the GraphQL impl
+ *     in `impl/graphql/pending-review.js`. Identical behaviour to what
+ *     `GitHubClient` did before the Phase 3 refactor.
+ *   - `"rest"`: delegates to `impl/rest/pending-review.js`. The REST
+ *     implementation produces the same return shape as the GraphQL impl.
+ *     Note that `getReviewById` requires a `prContext` because the
+ *     REST API identifies a review by (owner, repo, pull_number,
+ *     review_id) rather than by node id alone.
+ *   - `"host"`: not yet implemented — Phase 5 will add it (no host
+ *     extension is currently defined for this area).
+ *
+ * The dispatch shape allows each call site to use the same function
+ * signature regardless of which transport actually runs underneath.
+ */
+
+const AREA = 'pending_review_check';
+// Modes actually implemented by the dispatcher below. Co-located with the
+// dispatch logic so validateRepoConfig() and the dispatcher can't drift.
+// `host` is reserved for Phase 5 and is not yet implemented.
+const IMPLEMENTED_MODES = new Set(['graphql', 'rest']);
+
+function selectFeature(features) {
+  return (features && features[AREA]) || 'graphql';
+}
+
+/**
+ * Fetch the pending review (if any) authored by the authenticated user.
+ *
+ * @param {Object} octokit - Octokit instance bound to the host's baseUrl
+ * @param {Object} features - Feature-flag object from the host binding
+ * @param {string} owner
+ * @param {string} repo
+ * @param {number} prNumber
+ * @returns {Promise<Object|null>}
+ */
+async function getPendingReviewForUser(octokit, features, owner, repo, prNumber) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.getPendingReviewForUser(octokit, owner, repo, prNumber);
+  }
+  if (mode === 'rest') {
+    return restImpl.getPendingReviewForUser(octokit, owner, repo, prNumber);
+  }
+  if (mode === 'host') {
+    throw new Error('Host implementation for pending_review_check not yet available (Phase 5)');
+  }
+  throw new Error(`Unknown features.pending_review_check value: "${mode}"`);
+}
+
+/**
+ * Fetch a review by its GraphQL/database node ID.
+ *
+ * @param {Object} octokit
+ * @param {Object} features
+ * @param {string} nodeId
+ * @param {Object} [prContext] - { owner, repo, prNumber, reviewId? }
+ *   REQUIRED when `features.pending_review_check === "rest"` because the
+ *   REST endpoint identifies a review by (owner, repo, pull_number,
+ *   review_id) rather than by node id. Optional for the GraphQL path.
+ * @returns {Promise<Object|null>}
+ */
+async function getReviewById(octokit, features, nodeId, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.getReviewById(octokit, nodeId);
+  }
+  if (mode === 'rest') {
+    return restImpl.getReviewById(octokit, nodeId, prContext);
+  }
+  if (mode === 'host') {
+    throw new Error('Host implementation for pending_review_check not yet available (Phase 5)');
+  }
+  throw new Error(`Unknown features.pending_review_check value: "${mode}"`);
+}
+
+module.exports = {
+  getPendingReviewForUser,
+  getReviewById,
+  AREA,
+  IMPLEMENTED_MODES
+};

package/src/github/operations/review-lifecycle.js

@@ -0,0 +1,126 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const graphqlImpl = require('../impl/graphql/review-lifecycle');
+const restImpl = require('../impl/rest/review-lifecycle');
+
+/**
+ * Dispatcher for the `review_lifecycle` area:
+ *   - addPullRequestReview (creates a pending review)
+ *   - addPullRequestReviewWithBody (creates a pending review with a body)
+ *   - submitPullRequestReview (submits a pending review with an event)
+ *   - deletePullRequestReview (deletes a pending review)
+ *
+ * Each operation inspects `features.review_lifecycle`:
+ *   - `"graphql"` (default for github.com): delegates to the GraphQL impl
+ *     in `impl/graphql/review-lifecycle.js`. Identical behaviour to what
+ *     `GitHubClient` did before the Phase 3 refactor.
+ *   - `"rest"`: delegates to `impl/rest/review-lifecycle.js`. The REST
+ *     impl requires a `prContext = { owner, repo, prNumber, reviewId? }`
+ *     because REST endpoints identify the review by
+ *     (owner, repo, pull_number, review_id) rather than by node id.
+ *   - `"host"`: not yet implemented — Phase 5 (no current host extension).
+ */
+
+const AREA = 'review_lifecycle';
+// Modes actually implemented by the dispatcher below. Co-located with the
+// dispatch logic so validateRepoConfig() and the dispatcher can't drift.
+// `host` is reserved for Phase 5 and is not yet implemented.
+const IMPLEMENTED_MODES = new Set(['graphql', 'rest']);
+
+function selectFeature(features) {
+  return (features && features[AREA]) || 'graphql';
+}
+
+function notYetAvailable(mode) {
+  if (mode === 'host') {
+    throw new Error('Host implementation for review_lifecycle not yet available (Phase 5)');
+  }
+  throw new Error(`Unknown features.review_lifecycle value: "${mode}"`);
+}
+
+/**
+ * Create a pending review (no body).
+ *
+ * @param {Object} octokit
+ * @param {Object} features
+ * @param {string} prNodeId - GraphQL node id; required for GraphQL, accepted for REST signature parity
+ * @param {Object} [prContext] - { owner, repo, prNumber } — REQUIRED for REST mode
+ */
+async function addPullRequestReview(octokit, features, prNodeId, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.addPullRequestReview(octokit, prNodeId);
+  }
+  if (mode === 'rest') {
+    return restImpl.addPullRequestReview(octokit, prNodeId, prContext);
+  }
+  notYetAvailable(mode);
+}
+
+/**
+ * Create a pending review with a body.
+ *
+ * @param {Object} octokit
+ * @param {Object} features
+ * @param {string} prNodeId
+ * @param {string|null} body
+ * @param {Object} [prContext] - { owner, repo, prNumber } — REQUIRED for REST mode
+ */
+async function addPullRequestReviewWithBody(octokit, features, prNodeId, body, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.addPullRequestReviewWithBody(octokit, prNodeId, body);
+  }
+  if (mode === 'rest') {
+    return restImpl.addPullRequestReviewWithBody(octokit, prNodeId, body, prContext);
+  }
+  notYetAvailable(mode);
+}
+
+/**
+ * Submit a pending review.
+ *
+ * @param {Object} octokit
+ * @param {Object} features
+ * @param {string|number} reviewId
+ * @param {string} event - APPROVE | REQUEST_CHANGES | COMMENT
+ * @param {string|null} body
+ * @param {Object} [prContext] - { owner, repo, prNumber, reviewId? } — REQUIRED for REST mode
+ */
+async function submitPullRequestReview(octokit, features, reviewId, event, body, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.submitPullRequestReview(octokit, reviewId, event, body);
+  }
+  if (mode === 'rest') {
+    return restImpl.submitPullRequestReview(octokit, reviewId, event, body, prContext);
+  }
+  notYetAvailable(mode);
+}
+
+/**
+ * Delete a pending review.
+ *
+ * @param {Object} octokit
+ * @param {Object} features
+ * @param {string|number} reviewId
+ * @param {Object} [prContext] - { owner, repo, prNumber, reviewId? } — REQUIRED for REST mode
+ */
+async function deletePullRequestReview(octokit, features, reviewId, prContext) {
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.deletePullRequestReview(octokit, reviewId);
+  }
+  if (mode === 'rest') {
+    return restImpl.deletePullRequestReview(octokit, reviewId, prContext);
+  }
+  notYetAvailable(mode);
+}
+
+module.exports = {
+  addPullRequestReview,
+  addPullRequestReviewWithBody,
+  submitPullRequestReview,
+  deletePullRequestReview,
+  AREA,
+  IMPLEMENTED_MODES
+};

package/src/github/operations/stack-walker.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const graphqlImpl = require('../impl/graphql/stack-walker');
+const restImpl = require('../impl/rest/stack-walker');
+
+/**
+ * Dispatcher for the `stack_walker` area.
+ *
+ * `walkPRStack` historically accepted a `client` (with `.octokit.graphql`).
+ * To preserve backward compatibility while still routing through the
+ * dispatcher, this module accepts either:
+ *   - the new signature `(octokit, features, owner, repo, prNumber, _deps)`
+ *   - the legacy signature `(client, owner, repo, prNumber, _deps)` where
+ *     `client` looks like `{ octokit }` and the features map is omitted.
+ *
+ * `features.stack_walker` selects the transport:
+ *   - `"graphql"` (default for github.com): delegates to
+ *     `impl/graphql/stack-walker.js`.
+ *   - `"rest"`: delegates to `impl/rest/stack-walker.js`. Returns the
+ *     same ordered stack shape; PR `state` is normalised to GraphQL's
+ *     uppercase form so consumers don't need to branch.
+ *   - `"host"`: not yet implemented — Phase 5.
+ */
+
+const AREA = 'stack_walker';
+// Modes actually implemented by the dispatcher below. Co-located with the
+// dispatch logic so validateRepoConfig() and the dispatcher can't drift.
+// `host` is reserved for Phase 5 and is not yet implemented.
+const IMPLEMENTED_MODES = new Set(['graphql', 'rest']);
+
+function selectFeature(features) {
+  return (features && features[AREA]) || 'graphql';
+}
+
+/**
+ * Walk a PR stack starting from a given PR.
+ *
+ * Detects whether it has been called with the new dispatcher signature
+ * `(octokit, features, owner, repo, prNumber, _deps)` or the legacy
+ * `(client, owner, repo, prNumber, _deps)` shape used by the original
+ * `stack-walker.js` module so the existing call sites
+ * (`src/routes/pr.js`, tests) keep working without modification.
+ */
+async function walkPRStack(arg0, arg1, arg2, arg3, arg4, arg5) {
+  let octokit;
+  let features;
+  let owner;
+  let repo;
+  let prNumber;
+  let deps;
+
+  // Legacy shape: arg0 is a GitHubClient-like object with .octokit.
+  if (arg0 && typeof arg0 === 'object' && arg0.octokit) {
+    octokit = arg0.octokit;
+    // Legacy callers don't pass features; treat as default github.com.
+    features = arg0.binding?.features;
+    owner = arg1;
+    repo = arg2;
+    prNumber = arg3;
+    deps = arg4;
+  } else {
+    octokit = arg0;
+    features = arg1;
+    owner = arg2;
+    repo = arg3;
+    prNumber = arg4;
+    deps = arg5;
+  }
+
+  const mode = selectFeature(features);
+  if (mode === 'graphql') {
+    return graphqlImpl.walkPRStack(octokit, owner, repo, prNumber, deps);
+  }
+  if (mode === 'rest') {
+    return restImpl.walkPRStack(octokit, owner, repo, prNumber, deps);
+  }
+  if (mode === 'host') {
+    throw new Error('Host implementation for stack_walker not yet available (Phase 5)');
+  }
+  throw new Error(`Unknown features.stack_walker value: "${mode}"`);
+}
+
+module.exports = {
+  walkPRStack,
+  DEFAULT_TRUNK_BRANCHES: graphqlImpl.DEFAULT_TRUNK_BRANCHES,
+  AREA,
+  IMPLEMENTED_MODES
+};