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

package/src/github/parser.js

@@ -1,19 +1,39 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const simpleGit = require('simple-git');
 const path = require('path');
+const { matchRepoByUrl } = require('../config');
 
 /**
  * Parse command line arguments to extract PR information
  */
 class PRArgumentParser {
-  constructor() {
+  /**
+   * @param {Object} [config] - Optional pair-review config. When provided,
+   *   per-repo `url_pattern` regexes are tried before the built-in GitHub
+   *   and Graphite URL parsers, allowing pasted URLs from alternate hosts
+   *   to be resolved to the correct repo entry. The canonical
+   *   `owner/repo` from the config key (or named capture groups) takes
+   *   precedence over any host-specific parsing.
+   */
+  constructor(config = null) {
     this.git = simpleGit();
+    this.config = config;
   }
 
   /**
-   * Parse PR arguments from command line
+   * Parse PR arguments from command line.
+   *
+   * Returns at minimum `{ owner, repo, number }`. When the input was
+   * matched against a per-repo `url_pattern`, the returned object also
+   * includes `bindingRepository` — the `repos[...]` config key that was
+   * matched. Callers performing a host-binding lookup should prefer
+   * `bindingRepository` over `${owner}/${repo}` so monorepo-style configs
+   * where the URL pattern matches multiple sub-repos resolve to the
+   * correct entry. When `bindingRepository` is absent, callers should
+   * fall back to `${owner}/${repo}`.
+   *
    * @param {Array<string>} args - Command line arguments
-   * @returns {Promise<Object>} Parsed PR information { owner, repo, number }
+   * @returns {Promise<{owner: string, repo: string, number: number, bindingRepository?: string}>}
    */
   async parsePRArguments(args) {
     if (args.length === 0) {
@@ -38,9 +58,54 @@ class PRArgumentParser {
     return { owner, repo, number: prNumber };
   }
 
+  /**
+   * Match a URL against any configured `url_pattern` regex in the repos
+   * config. Returns `{ owner, repo, number, bindingRepository }` when a
+   * match yields a complete triple (owner+repo+number), otherwise null.
+   * Used to resolve URLs pasted from alternate Git hosts before falling
+   * back to the built-in GitHub/Graphite parsers.
+   *
+   * `bindingRepository` is the matched `repos[...]` config key — use it
+   * to look up the host binding (token, api_host, features) when the
+   * captured owner/repo differ from the config key.
+   *
+   * @param {string} url - The URL to match
+   * @returns {Object|null} `{ owner, repo, number, bindingRepository }` or null
+   * @private
+   */
+  _matchUrlPatternFromConfig(url) {
+    if (!this.config) return null;
+    const match = matchRepoByUrl(url, this.config);
+    if (!match) return null;
+
+    // Derive owner/repo: prefer named capture groups, fall back to the
+    // canonical "owner/repo" repository key from config.
+    let { owner, repo, number } = match;
+    if ((!owner || !repo) && match.repository && match.repository.includes('/')) {
+      const [keyOwner, keyRepo] = match.repository.split('/');
+      if (!owner) owner = keyOwner;
+      if (!repo) repo = keyRepo;
+    }
+
+    if (!owner || !repo || typeof number !== 'number' || isNaN(number) || number <= 0) {
+      return null;
+    }
+    return {
+      owner,
+      repo,
+      number,
+      bindingRepository: match.bindingRepository
+    };
+  }
+
   /**
    * Parse a PR URL string and extract owner, repo, and PR number
-   * Handles both GitHub and Graphite URLs, with or without protocol
+   * Handles both GitHub and Graphite URLs, with or without protocol.
+   *
+   * When the parser was constructed with a config, per-repo `url_pattern`
+   * regexes are tried first so that alternate-host URLs resolve to the
+   * canonical owner/repo from config.
+   *
    * @param {string} url - The PR URL to parse
    * @returns {Object|null} { owner, repo, number } or null if not a valid PR URL
    */
@@ -49,6 +114,14 @@ class PRArgumentParser {
       return null;
     }
 
+    // Try config-driven URL pattern matching first. This handles
+    // alternate-host URLs and lets host-specific repos override the
+    // built-in github.com path if they choose.
+    const configMatch = this._matchUrlPatternFromConfig(url.trim());
+    if (configMatch) {
+      return configMatch;
+    }
+
     // Clean up the URL - trim whitespace
     let normalizedUrl = url.trim();
 
@@ -219,9 +292,162 @@ class PRArgumentParser {
       return { owner: match[1], repo: match[2] };
     }
 
+    // Fall through to config-driven alt-host matching. Only consulted
+    // when the built-in github.com patterns don't match, so common-case
+    // github.com behaviour is unchanged. Requires the parser to have
+    // been constructed with a config; otherwise short-circuits and
+    // throws.
+    const altHostMatch = this._parseAltHostRepositoryFromURL(url);
+    if (altHostMatch) {
+      return altHostMatch;
+    }
+
     throw new Error('Current directory is not a git repository or has no GitHub remote origin');
   }
 
+  /**
+   * Try to resolve a non-github.com git remote URL to a configured repo
+   * entry. Walks `this.config.repos` looking for entries that declare an
+   * `api_host` (alt-host repos) and matches the URL against patterns
+   * derived from that host + the canonical "owner/repo" config key.
+   *
+   * Match order per repo entry:
+   *   1. The optional `git_remote_pattern` escape hatch (a regex string).
+   *      When present, it is tried FIRST so users with non-standard
+   *      remote URL layouts can opt in. If the regex matches anywhere
+   *      in the remote URL, the canonical config key is returned.
+   *   2. Patterns derived from `api_host` + canonical "owner/repo" key:
+   *        - `https://<host>/<owner>/<repo>(.git)?`
+   *        - `http://<host>/<owner>/<repo>(.git)?`  (for self-hosted dev)
+   *        - `git@<host>:<owner>/<repo>(.git)?`
+   *      The host portion of `api_host` is used as-is for HTTP(S)
+   *      patterns (it may already include a scheme/port — we strip the
+   *      scheme to derive the bare host for the SSH form).
+   *
+   * First match wins; the canonical "owner/repo" from the config KEY is
+   * returned (named groups in `git_remote_pattern` are not consulted —
+   * the contract is "if the regex matches the URL, the repo entry
+   * applies").
+   *
+   * Returns null when no entry matches (or when no config is available),
+   * letting the caller fall through to its existing error path.
+   *
+   * @param {string} url - Git remote URL
+   * @returns {Object|null} { owner, repo } or null
+   * @private
+   */
+  _parseAltHostRepositoryFromURL(url) {
+    if (!url || typeof url !== 'string') return null;
+    if (!this.config || !this.config.repos || typeof this.config.repos !== 'object') {
+      return null;
+    }
+
+    for (const [repoKey, repoEntry] of Object.entries(this.config.repos)) {
+      if (!repoEntry || typeof repoEntry !== 'object') continue;
+      const apiHost = (typeof repoEntry.api_host === 'string' && repoEntry.api_host)
+        ? repoEntry.api_host
+        : null;
+      // Only alt-host repos participate here. github.com repos take the
+      // built-in fast path above.
+      if (!apiHost) continue;
+
+      // 1. Escape hatch: per-repo git_remote_pattern. We treat it as a
+      //    regex (consistent with the existing url_pattern field) and
+      //    use RegExp#test so callers can omit `^` if they want a
+      //    substring-style match. validateRepoConfig() rejects invalid
+      //    regexes at startup; the try/catch here is purely defensive.
+      const remotePattern = repoEntry.git_remote_pattern;
+      if (typeof remotePattern === 'string' && remotePattern) {
+        try {
+          if (new RegExp(remotePattern).test(url)) {
+            const parts = this._splitRepoKey(repoKey);
+            if (parts) return parts;
+          }
+        } catch {
+          // Invalid regex — would have been caught at startup; skip.
+        }
+      }
+
+      const parts = this._splitRepoKey(repoKey);
+      if (!parts) continue;
+
+      // 2. Derive HTTPS/HTTP/SSH patterns from api_host. api_host may
+      //    already include a scheme (and possibly a port + path like
+      //    "https://althost.example/api/v3"). Strip the scheme to get
+      //    the bare host[:port] that appears in git remote URLs.
+      const bareHost = this._bareHostFromApiHost(apiHost);
+      if (!bareHost) continue;
+
+      const escapedHost = this._escapeRegex(bareHost);
+      const escapedOwner = this._escapeRegex(parts.owner);
+      const escapedRepo = this._escapeRegex(parts.repo);
+
+      // Allow either https:// or http:// scheme (self-hosted dev
+      // instances sometimes use plain HTTP). Tolerate optional .git
+      // suffix. Anchored to start/end so we don't accidentally match
+      // a substring inside a different host's URL.
+      const httpRegex = new RegExp(
+        `^https?:\\/\\/${escapedHost}\\/${escapedOwner}\\/${escapedRepo}(?:\\.git)?$`,
+        'i'
+      );
+      if (httpRegex.test(url)) return parts;
+
+      const sshRegex = new RegExp(
+        `^git@${escapedHost}:${escapedOwner}\\/${escapedRepo}(?:\\.git)?$`,
+        'i'
+      );
+      if (sshRegex.test(url)) return parts;
+    }
+
+    return null;
+  }
+
+  /**
+   * Strip a scheme (and any trailing path) off an `api_host` config
+   * value to derive the bare host[:port] string that appears in a git
+   * remote URL. `api_host` is conventionally something like
+   * `https://althost.example/api/v3`, but bare `althost.example` is
+   * also accepted.
+   *
+   * @param {string} apiHost
+   * @returns {string|null} - Host[:port] or null when the value is unusable
+   * @private
+   */
+  _bareHostFromApiHost(apiHost) {
+    if (typeof apiHost !== 'string' || !apiHost) return null;
+    // Strip scheme if present.
+    let host = apiHost.replace(/^https?:\/\//i, '');
+    // Strip everything from the first slash onward (path component).
+    const slashIdx = host.indexOf('/');
+    if (slashIdx >= 0) host = host.slice(0, slashIdx);
+    return host || null;
+  }
+
+  /**
+   * Split a canonical "owner/repo" config key into { owner, repo }.
+   * Returns null when the key is malformed.
+   *
+   * @param {string} repoKey
+   * @returns {{owner: string, repo: string}|null}
+   * @private
+   */
+  _splitRepoKey(repoKey) {
+    if (typeof repoKey !== 'string') return null;
+    const idx = repoKey.indexOf('/');
+    if (idx <= 0 || idx === repoKey.length - 1) return null;
+    return { owner: repoKey.slice(0, idx), repo: repoKey.slice(idx + 1) };
+  }
+
+  /**
+   * Escape a string for safe embedding inside a regex literal.
+   * @param {string} s
+   * @returns {string}
+   * @private
+   */
+  _escapeRegex(s) {
+    return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
   /**
    * Validate PR arguments
    * @param {Object} prInfo - PR information { owner, repo, number }

package/src/github/stack-walker.js

@@ -1,196 +1,21 @@
 // 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.
+ * Backward-compatibility shim for the legacy `walkPRStack(client, ...)`
+ * signature. The real implementation now lives in
+ * `src/github/operations/stack-walker.js` (the dispatcher) and
+ * `src/github/impl/graphql/stack-walker.js` (the GraphQL implementation).
  *
- * @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
+ * Direct importers of this module (`src/routes/pr.js` and tests) pass a
+ * GitHubClient-like object as the first argument. The dispatcher accepts
+ * that shape and routes to the correct transport via
+ * `client.binding.features.stack_walker` when present, defaulting to
+ * `"graphql"` otherwise — preserving pre-refactor behaviour exactly.
  */
-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;
-}
+const operations = require('./operations/stack-walker');
 
-module.exports = { walkPRStack, DEFAULT_TRUNK_BRANCHES };
+module.exports = {
+  walkPRStack: operations.walkPRStack,
+  DEFAULT_TRUNK_BRANCHES: operations.DEFAULT_TRUNK_BRANCHES
+};