@in-the-loop-labs/pair-review 4.0.0 → 4.1.0

package/src/github/client.js

@@ -1137,6 +1137,43 @@ class GitHubClient {
     });
   }
 
+  /**
+   * List open pull requests for a single repository via the REST API.
+   *
+   * Used by the dashboard collections sweep against alt-hosts, which speak a
+   * REST subset and generally have no Search API. The returned rows carry the
+   * classification fields (`author`, `requested_reviewers`, `requested_teams`)
+   * so the caller can bucket each PR into a collection locally, plus the same
+   * display fields `searchPullRequests` returns so both paths cache uniformly.
+   *
+   * @param {string} owner - Repository owner
+   * @param {string} repo - Repository name
+   * @returns {Promise<Array<{owner: string, repo: string, number: number, title: string, author: string|null, updated_at: string, html_url: string, state: string, requested_reviewers: string[], requested_teams: string[]}>>}
+   */
+  async listOpenPullRequests(owner, repo) {
+    const pulls = await this.octokit.paginate(
+      this.octokit.rest.pulls.list,
+      { owner, repo, state: 'open', per_page: 100 }
+    );
+
+    return pulls.map(pr => ({
+      owner,
+      repo,
+      number: pr.number,
+      title: pr.title,
+      author: pr.user?.login || null,
+      updated_at: pr.updated_at,
+      html_url: pr.html_url,
+      state: pr.state,
+      requested_reviewers: Array.isArray(pr.requested_reviewers)
+        ? pr.requested_reviewers.map(r => r && r.login).filter(Boolean)
+        : [],
+      requested_teams: Array.isArray(pr.requested_teams)
+        ? pr.requested_teams.map(t => t && t.slug).filter(Boolean)
+        : []
+    }));
+  }
+
   /**
    * Get the authenticated user's information.
    * @returns {Promise<{login: string, name: string, avatar_url: string}>}

package/src/github/parser.js

@@ -90,11 +90,20 @@ class PRArgumentParser {
     if (!owner || !repo || typeof number !== 'number' || isNaN(number) || number <= 0) {
       return null;
     }
+    // Carry the matched repo's `api_host` so downstream setup binds the PR to
+    // the alternate host without probing. A `url_pattern` match on a repo with
+    // no `api_host` (a plain github.com entry) resolves to `host: null`.
+    const matchedApiHost = (match.repoConfig
+      && typeof match.repoConfig.api_host === 'string'
+      && match.repoConfig.api_host)
+      ? match.repoConfig.api_host
+      : null;
     return {
       owner,
       repo,
       number,
-      bindingRepository: match.bindingRepository
+      bindingRepository: match.bindingRepository,
+      host: matchedApiHost
     };
   }
 
@@ -114,16 +123,30 @@ class PRArgumentParser {
       return null;
     }
 
+    // Clean up the URL - trim whitespace
+    const trimmedUrl = url.trim();
+
     // 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());
+    const configMatch = this._matchUrlPatternFromConfig(trimmedUrl);
     if (configMatch) {
-      return configMatch;
+      // INVARIANT: an `api_host`-bearing `url_pattern` must NEVER bind a
+      // canonical github.com / Graphite URL. An over-broad or unanchored pattern
+      // can match one and pre-pin it to the alt host (an explicit host bypasses
+      // the setup probe → a silent, durable wrong binding). When the config
+      // match carries an alt host but the URL is a canonical github/graphite URL,
+      // discard the match and fall through to the built-in parsers (host: null).
+      const sansProtocol = trimmedUrl.replace(/^https?:\/\//i, '');
+      const isCanonicalHostUrl = sansProtocol.startsWith('github.com/')
+        || sansProtocol.startsWith('app.graphite.dev/')
+        || sansProtocol.startsWith('app.graphite.com/');
+      if (!(configMatch.host && isCanonicalHostUrl)) {
+        return configMatch;
+      }
     }
 
-    // Clean up the URL - trim whitespace
-    let normalizedUrl = url.trim();
+    let normalizedUrl = trimmedUrl;
 
     // Add https:// if no protocol is present
     if (normalizedUrl.startsWith('github.com')) {
@@ -222,7 +245,9 @@ class PRArgumentParser {
    * @param {string} repo - Repository name
    * @param {string} numberStr - PR number as string
    * @param {string} source - Source name for error messages ('GitHub' or 'Graphite')
-   * @returns {Object} Validated PR info { owner, repo, number }
+   * @returns {Object} Validated PR info `{ owner, repo, number, host? }`. `host`
+   *   is `null` for github.com/Graphite URLs (definitively github); it is OMITTED
+   *   (undefined) for the pair-review:// scheme, which carries no host in its path.
    * @private
    */
   _createPRInfo(owner, repo, numberStr, source) {
@@ -237,7 +262,16 @@ class PRArgumentParser {
       throw new Error(`Invalid ${source} URL format. Expected: ${exampleUrl}`);
     }
 
-    return { owner, repo, number };
+    // A github.com or Graphite URL unambiguously identifies a github.com PR, so
+    // the host is explicitly null (not "unknown"). The pair-review:// scheme
+    // carries NO host in its path and is not github-only, so leave `host`
+    // undefined — it flows into the probe/derive path like a bare number,
+    // instead of self-healing (dual repo) or throwing (exclusive alt) on github.
+    const result = { owner, repo, number };
+    if (source !== 'pair-review://') {
+      result.host = null;
+    }
+    return result;
   }
 
   /**

package/src/interactive-analysis-config.js

@@ -93,7 +93,7 @@ async function resolveCliInstructions(flags) {
  * @param {Object} params
  * @param {Object} params.db - Database instance
  * @param {Object} params.config - Loaded global config
- * @param {Object} params.flags - Parsed CLI flags (council/model/instructions)
+ * @param {Object} params.flags - Parsed CLI flags (council/provider/model/instructions)
  * @param {string} params.repository - owner/repo (for repo-default resolution)
  * @returns {Promise<Object|null>} The analysisConfig object, or null when no instructions.
  */
@@ -104,7 +104,7 @@ async function buildInteractiveAnalysisConfig({ db, config, flags, repository })
   const reviewConfig = await resolveReviewConfig(
     db,
     repository,
-    { council: flags.council, model: flags.model },
+    { council: flags.council, provider: flags.provider, model: flags.model },
     config
   );
 

package/src/links/repo-links.js

@@ -31,6 +31,7 @@
  */
 
 const { getRepoConfig } = require('../config');
+const { isDualHostRepoConfig } = require('../utils/host-resolution');
 const logger = require('../utils/logger');
 
 // Whitelist of allowed `{placeholder}` names. Anything else in the template
@@ -158,13 +159,28 @@ function sanitizeSvgIcon(svg) {
  * malformed), a warning is logged and `icon` becomes `null` — the link
  * is still rendered, just without a custom icon.
  *
+ * **Per-PR host awareness (dual-host repos only).** `host` is the PR's
+ * resolved host: `null` = github.com, an `api_host` URL string = the alt
+ * host, `undefined` = unknown / not applicable. It only affects a
+ * *dual-host* repo (`api_host` + `exclusive: false`):
+ *   - `host === null` (github-hosted PR) → keep the GitHub/Graphite links
+ *     (subject to any explicit `links.github/graphite: false`) and hide the
+ *     alt-host external link.
+ *   - `host === '<url>'` (alt-hosted PR) → keep the external link and hide
+ *     the GitHub/Graphite links.
+ * Exclusive alt-host repos and plain github repos ignore `host` entirely, so
+ * existing two-arg callers (and `host === undefined`) render byte-identically
+ * to before this parameter existed.
+ *
  * @param {Object} config
  * @param {string} repository  Canonical `owner/repo` identifier
+ * @param {string|null} [host]  PR's resolved host: null=github, url=alt,
+ *                              undefined=unknown/not applicable
  * @returns {{ external: { label: string, url_template: string, icon: string|null }|null,
  *             github: boolean,
  *             graphite: boolean }}
  */
-function resolveRepoLinks(config, repository) {
+function resolveRepoLinks(config, repository, host = undefined) {
   const result = { external: null, github: true, graphite: true };
   if (!config || !repository) return result;
 
@@ -172,33 +188,47 @@ function resolveRepoLinks(config, repository) {
   if (!repoConfig || typeof repoConfig !== 'object') return result;
 
   const links = repoConfig.links;
-  if (!links || typeof links !== 'object') return result;
-
-  if (links.github === false) result.github = false;
-  if (links.graphite === false) result.graphite = false;
-
-  const ext = links.external;
-  if (ext && typeof ext === 'object'
-      && typeof ext.label === 'string' && ext.label
-      && typeof ext.url_template === 'string'
-      && ext.url_template.startsWith('https://')) {
-    let icon = null;
-    if (ext.icon !== undefined && ext.icon !== null && ext.icon !== '') {
-      icon = sanitizeSvgIcon(ext.icon);
-      if (icon === null) {
-        logger.warn(
-          `Dropping links.external.icon for "${repository}" — failed sanitisation.`
-        );
+  if (links && typeof links === 'object') {
+    if (links.github === false) result.github = false;
+    if (links.graphite === false) result.graphite = false;
+
+    const ext = links.external;
+    if (ext && typeof ext === 'object'
+        && typeof ext.label === 'string' && ext.label
+        && typeof ext.url_template === 'string'
+        && ext.url_template.startsWith('https://')) {
+      let icon = null;
+      if (ext.icon !== undefined && ext.icon !== null && ext.icon !== '') {
+        icon = sanitizeSvgIcon(ext.icon);
+        if (icon === null) {
+          logger.warn(
+            `Dropping links.external.icon for "${repository}" — failed sanitisation.`
+          );
+        }
       }
+      result.external = {
+        // Optional host display name (e.g. "Meteorite"). When absent, the
+        // field is null and consumers fall back to "GitHub" via resolveHostName.
+        name: (typeof ext.name === 'string' && ext.name) ? ext.name : null,
+        label: ext.label,
+        url_template: ext.url_template,
+        icon
+      };
+    }
+  }
+
+  // Per-PR host awareness for dual-host repos. A `host` of `undefined`
+  // (omitted arg, unknown host) leaves the repo-level result untouched, so
+  // non-dual repos and legacy two-arg callers are unaffected.
+  if (host !== undefined && isDualHostRepoConfig(repoConfig)) {
+    if (host === null) {
+      // github-hosted PR: the alt-host external link does not apply.
+      result.external = null;
+    } else {
+      // alt-hosted PR: hide the GitHub/Graphite links, keep the external one.
+      result.github = false;
+      result.graphite = false;
     }
-    result.external = {
-      // Optional host display name (e.g. "Meteorite"). When absent, the
-      // field is null and consumers fall back to "GitHub" via resolveHostName.
-      name: (typeof ext.name === 'string' && ext.name) ? ext.name : null,
-      label: ext.label,
-      url_template: ext.url_template,
-      icon
-    };
   }
 
   return result;
@@ -212,12 +242,20 @@ function resolveRepoLinks(config, repository) {
  * `"GitHub"`. This is the server-side counterpart to the frontend
  * `window.RepoLinks.hostName()` accessor.
  *
+ * Host-aware for dual-host repos: a github-hosted PR (`host === null`)
+ * reports "GitHub" even when an external name is configured, because
+ * `resolveRepoLinks` clears the external link for that host. See
+ * `resolveRepoLinks` for the `host` semantics. Non-dual repos and two-arg
+ * callers behave exactly as before.
+ *
  * @param {Object} config
  * @param {string} repository  Canonical `owner/repo` identifier
+ * @param {string|null} [host]  PR's resolved host: null=github, url=alt,
+ *                              undefined=unknown/not applicable
  * @returns {string} The configured host name, or "GitHub" by default
  */
-function resolveHostName(config, repository) {
-  const links = resolveRepoLinks(config, repository);
+function resolveHostName(config, repository, host = undefined) {
+  const links = resolveRepoLinks(config, repository, host);
   return (links.external && links.external.name) ? links.external.name : 'GitHub';
 }
 

package/src/local-review.js

@@ -11,7 +11,7 @@ const { fireHooks, hasHooks } = require('./hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = require('./hooks/payloads');
 
 const execAsync = promisify(exec);
-const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel, reviewScope } = require('./local-scope');
+const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel, reviewScope, parseScopeArg } = require('./local-scope');
 const { initializeDatabase, ReviewRepository, RepoSettingsRepository } = require('./database');
 const { resolveCouncilHandle } = require('./councils/resolve-council');
 const { prepareInteractiveAnalysisConfig } = require('./interactive-analysis-config');
@@ -21,6 +21,10 @@ const summaryGenerator = require('./ai/summary-generator');
 const tourGenerator = require('./ai/tour-generator');
 const { getShaAbbrevLength } = require('./git/sha-abbrev');
 const { GIT_DIFF_FLAGS, GIT_DIFF_FLAGS_ARRAY } = require('./git/diff-flags');
+// Namespace import (not destructured) so detectBaseBranch is resolved off the
+// module object at call time — this keeps it interceptable by vi.spyOn on the
+// base-branch module in tests, unlike a destructured binding captured at load.
+const baseBranchModule = require('./git/base-branch');
 const open = (...args) => process.env.PAIR_REVIEW_NO_OPEN ? Promise.resolve() : import('open').then(({ default: open }) => open(...args));
 
 // Design note: This module uses execSync for git commands despite async function signatures.
@@ -694,6 +698,112 @@ async function generateLocalDiff(repoPath, options = {}) {
   };
 }
 
+/**
+ * Resolve the effective scope and base branch for a local review session,
+ * applying an explicit `--scope`/`--base` (or delegated query) override on top
+ * of the persisted/default scope.
+ *
+ * Shared by the CLI seam (setupLocalReviewSession) and the web setup seam
+ * (src/setup/local-setup.js) so a scoped launch behaves identically whether it
+ * cold-starts a server or is delegated to a running one. Callers MUST have
+ * validated flags.scope/flags.base first (parseScopeArg + branch-name regex +
+ * "base requires branch scope"); an invalid flags.scope is treated as "no
+ * override" here rather than throwing.
+ *
+ * Precedence — scope: explicit override > persisted review scope > DEFAULT_SCOPE.
+ * Precedence — base: explicit --base > persisted local_base_branch >
+ * detectBaseBranch. The base is nulled for any non-branch scope so a stale value
+ * from a previously branch-scoped session never leaks into the diff/persist/return.
+ *
+ * @param {Object} params
+ * @param {Object|null} params.existingReview - Persisted review row, or null for a fresh session
+ * @param {Object} [params.flags] - { scope?, base? }
+ * @param {string} params.repoPath
+ * @param {string} params.branch - Current branch name
+ * @param {string} params.repository - owner/repo (for host binding / PR base lookup)
+ * @param {Object} params.config
+ * @returns {Promise<{scopeStart: string, scopeEnd: string, baseBranch: string|null, scopeOverridden: boolean}>}
+ */
+async function resolveScopeAndBase({ existingReview, flags = {}, repoPath, branch, repository, config }) {
+  const scopeOverride = flags.scope ? parseScopeArg(flags.scope) : null;
+  let scopeStart, scopeEnd;
+  if (scopeOverride) {
+    ({ start: scopeStart, end: scopeEnd } = scopeOverride);
+  } else if (existingReview) {
+    ({ start: scopeStart, end: scopeEnd } = reviewScope(existingReview));
+  } else {
+    ({ start: scopeStart, end: scopeEnd } = DEFAULT_SCOPE);
+  }
+
+  let baseBranch = existingReview?.local_base_branch || null;
+  if (scopeOverride && includesBranch(scopeStart)) {
+    if (flags.base) {
+      baseBranch = flags.base;
+    } else if (!baseBranch) {
+      const branchBinding = repository ? resolveHostBinding(repository, config) : null;
+      const token = branchBinding?.token || getGitHubToken(config);
+      const detection = await baseBranchModule.detectBaseBranch(repoPath, branch, {
+        repository,
+        enableGraphite: config?.enable_graphite === true,
+        _deps: (token || branchBinding) ? {
+          getGitHubToken: () => token || '',
+          getHostBinding: () => branchBinding || null
+        } : undefined
+      });
+      if (!detection) {
+        throw new Error(
+          `Could not detect a base branch for scope '${scopeStart}..${scopeEnd}'. ` +
+          'Pass --base <branch> to specify one explicitly.'
+        );
+      }
+      baseBranch = detection.baseBranch;
+    }
+  }
+
+  // A non-branch scope has no base branch. Drop any value seeded from a
+  // previously branch-scoped session so the stale base never reaches the diff,
+  // the persisted row, or the returned session — matching the web set-scope
+  // route, which persists null when leaving branch scope.
+  if (!includesBranch(scopeStart)) {
+    baseBranch = null;
+  }
+
+  return { scopeStart, scopeEnd, baseBranch, scopeOverridden: !!scopeOverride };
+}
+
+/**
+ * Persist an explicitly-overridden scope (and its resolved base) and auto-name
+ * the review when a branch scope is newly applied to an unnamed review. Call
+ * ONLY after generateScopedDiff succeeds, so a scope whose diff fails (e.g. a
+ * bad --base) never sticks. Shared by the CLI and web setup seams. Caller gates
+ * this on `scopeOverridden` — it always writes when invoked.
+ *
+ * @param {Object} params
+ * @param {Object} params.reviewRepo - ReviewRepository instance
+ * @param {number} params.sessionId
+ * @param {Object|null} params.existingReview
+ * @param {string} params.scopeStart
+ * @param {string} params.scopeEnd
+ * @param {string|null} params.baseBranch
+ * @param {string} params.branch - Current branch (stored as head branch for branch scopes)
+ * @param {string} params.repoPath
+ */
+async function persistScopeSelection({ reviewRepo, sessionId, existingReview, scopeStart, scopeEnd, baseBranch, branch, repoPath }) {
+  await reviewRepo.updateLocalScope(sessionId, scopeStart, scopeEnd, baseBranch, branch);
+
+  // Keep CLI and web set-scope in sync: when a branch scope is newly applied to
+  // an as-yet-unnamed review, auto-name it from the first commit subject.
+  // Mirrors routes/local.js set-scope. A fresh session has no existing review,
+  // which counts as both unnamed and previously non-branch.
+  const oldScopeStart = existingReview ? reviewScope(existingReview).start : DEFAULT_SCOPE.start;
+  if (!existingReview?.name && includesBranch(scopeStart) && !includesBranch(oldScopeStart) && baseBranch) {
+    const firstSubject = await module.exports.getFirstCommitSubject(repoPath, baseBranch);
+    if (firstSubject) {
+      await reviewRepo.updateReview(sessionId, { name: firstSubject.slice(0, 200) });
+    }
+  }
+}
+
 /**
  * Set up a local review session: resolve git state, persist the diff,
  * and enqueue the background summary job. Caller is responsible for
@@ -777,7 +887,11 @@ async function setupLocalReviewSession({ db, config, repoPath, flags = {}, start
     console.log(`Created new review session (ID: ${sessionId})`);
   }
 
-  const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
+  // Resolve scope + base (explicit --scope/--base override > persisted > default)
+  // via the shared helper so the CLI and delegated web-setup seam stay identical.
+  const { scopeStart, scopeEnd, baseBranch, scopeOverridden } = await resolveScopeAndBase({
+    existingReview, flags, repoPath, branch, repository, config
+  });
 
   const hookEvent = existingReview ? 'review.loaded' : 'review.started';
   if (hasHooks(hookEvent, config)) {
@@ -790,11 +904,20 @@ async function setupLocalReviewSession({ db, config, repoPath, flags = {}, start
       fireHooks(hookEvent, payload, config);
     }).catch(err => { logger.warn(`Review hook failed: ${err.message}`); });
   }
-  const baseBranch = existingReview?.local_base_branch || null;
 
   console.log(`Generating diff for scope: ${scopeLabel(scopeStart, scopeEnd)}...`);
   const { diff, stats } = await module.exports.generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch);
 
+  // Persist an explicitly-requested scope (and its resolved base) so the web UI
+  // later opens with the same scope. Only after generateScopedDiff succeeds, so a
+  // scope whose diff fails (e.g. a bad --base) never sticks. Never touch persisted
+  // scope when no override was supplied.
+  if (scopeOverridden) {
+    await persistScopeSelection({
+      reviewRepo, sessionId, existingReview, scopeStart, scopeEnd, baseBranch, branch, repoPath
+    });
+  }
+
   let branchInfo = null;
   if (!includesBranch(scopeStart)) {
     const untrackedFiles = await getUntrackedFiles(repoPath);
@@ -932,6 +1055,11 @@ async function handleLocalReview(targetPath, flags = {}) {
     if (flags.model && !flags.council) {
       process.env.PAIR_REVIEW_MODEL = flags.model;
     }
+    // Mirror --provider too so the local web/UI routes (which read
+    // PAIR_REVIEW_PROVIDER via getProvider(req)) honor it, matching --model above.
+    if (flags.provider) {
+      process.env.PAIR_REVIEW_PROVIDER = flags.provider;
+    }
 
     console.log('Starting server...');
     const port = await startServer(db);
@@ -1085,14 +1213,13 @@ async function detectAndBuildBranchInfo(repoPath, branch, options = {}) {
   if (untrackedFiles && untrackedFiles.length > 0) return null;
 
   try {
-    const { detectBaseBranch } = require('./git/base-branch');
     const depsOverride = githubToken || hostBinding
       ? {
           getGitHubToken: () => githubToken || '',
           getHostBinding: () => hostBinding || null
         }
       : undefined;
-    const detection = await detectBaseBranch(repoPath, branch, {
+    const detection = await baseBranchModule.detectBaseBranch(repoPath, branch, {
       repository,
       enableGraphite,
       _deps: depsOverride
@@ -1117,6 +1244,8 @@ async function detectAndBuildBranchInfo(repoPath, branch, options = {}) {
 module.exports = {
   handleLocalReview,
   setupLocalReviewSession,
+  resolveScopeAndBase,
+  persistScopeSelection,
   findGitRoot,
   findMainGitRoot,
   getHeadSha,

package/src/local-scope.js

@@ -15,6 +15,42 @@ function isValidScope(start, end) {
   return si !== -1 && ei !== -1 && si <= ei && si <= UNSTAGED_INDEX && ei >= UNSTAGED_INDEX;
 }
 
+/**
+ * The full set of valid scope ranges, formatted as `start..end` strings.
+ * Computed from STOPS + isValidScope so it stays the single source of truth.
+ * Ordered by STOPS position (branch-first).
+ * @type {string[]}
+ */
+const VALID_SCOPE_RANGES = (() => {
+  const ranges = [];
+  for (const start of STOPS) {
+    for (const end of STOPS) {
+      if (isValidScope(start, end)) ranges.push(`${start}..${end}`);
+    }
+  }
+  return ranges;
+})();
+
+/**
+ * Parse a `--scope` CLI argument of the form `<start>..<end>` into a scope
+ * object. Splits on `..`, trims each side, and delegates validation to
+ * isValidScope (the single source of truth). Single tokens, missing `..`,
+ * unknown stops, non-contiguous ranges, ranges excluding 'unstaged', and
+ * reversed ranges all return null.
+ *
+ * @param {string} value - Raw CLI value (e.g. 'branch..untracked')
+ * @returns {{ start: string, end: string }|null} Parsed scope, or null if invalid
+ */
+function parseScopeArg(value) {
+  if (typeof value !== 'string') return null;
+  const parts = value.split('..');
+  if (parts.length !== 2) return null;
+  const start = parts[0].trim();
+  const end = parts[1].trim();
+  if (!isValidScope(start, end)) return null;
+  return { start, end };
+}
+
 function normalizeScope(start, end) {
   if (isValidScope(start, end)) return { start, end };
   const si = STOPS.indexOf(start);
@@ -130,7 +166,9 @@ function scopeGitHints(start, end, baseBranch) {
 const LocalScope = {
   STOPS,
   DEFAULT_SCOPE,
+  VALID_SCOPE_RANGES,
   isValidScope,
+  parseScopeArg,
   normalizeScope,
   reviewScope,
   scopeIncludes,