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

package/src/database.js

@@ -21,7 +21,7 @@ function getDbPath() {
 /**
  * Current schema version - increment this when adding new migrations
  */
-const CURRENT_SCHEMA_VERSION = 46;
+const CURRENT_SCHEMA_VERSION = 48;
 
 /**
  * Database schema SQL statements
@@ -270,6 +270,36 @@ const SCHEMA_SQL = {
     )
   `,
 
+  hunk_summaries: `
+    CREATE TABLE IF NOT EXISTS hunk_summaries (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      review_id INTEGER NOT NULL,
+      file_path TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      summary_text TEXT,
+      trivial_reason TEXT,
+      provider TEXT,
+      model TEXT,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
+      CHECK (summary_text IS NOT NULL OR trivial_reason IS NOT NULL),
+      UNIQUE (review_id, content_hash)
+    )
+  `,
+
+  tours: `
+    CREATE TABLE IF NOT EXISTS tours (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      review_id INTEGER NOT NULL UNIQUE,
+      stops TEXT NOT NULL,
+      diff_hash TEXT NOT NULL,
+      provider TEXT,
+      model TEXT,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE
+    )
+  `,
+
   github_pr_cache: `
     CREATE TABLE IF NOT EXISTS github_pr_cache (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -365,6 +395,8 @@ const INDEX_SQL = [
   'CREATE INDEX IF NOT EXISTS idx_chat_messages_session ON chat_messages(session_id)',
   // Context files indexes
   'CREATE INDEX IF NOT EXISTS idx_context_files_review ON context_files(review_id)',
+  // Hunk summaries indexes
+  'CREATE INDEX IF NOT EXISTS idx_hunk_summaries_review ON hunk_summaries(review_id)',
   // GitHub PR cache indexes
   'CREATE UNIQUE INDEX IF NOT EXISTS idx_github_pr_cache_unique ON github_pr_cache(collection, owner, repo, number)',
   // Worktree pool indexes
@@ -2078,6 +2110,55 @@ const MIGRATIONS = {
 
     console.log('  Rebuilt external_comments with ON DELETE SET NULL on parent_id');
     console.log('Migration to schema version 46 complete');
+  },
+
+  47: (db) => {
+    console.log('Running migration to schema version 47: Add hunk_summaries table...');
+    if (!tableExists(db, 'hunk_summaries')) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS hunk_summaries (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          review_id INTEGER NOT NULL,
+          file_path TEXT NOT NULL,
+          content_hash TEXT NOT NULL,
+          summary_text TEXT,
+          trivial_reason TEXT,
+          provider TEXT,
+          model TEXT,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
+          CHECK (summary_text IS NOT NULL OR trivial_reason IS NOT NULL),
+          UNIQUE (review_id, content_hash)
+        )
+      `);
+      console.log('  Created hunk_summaries table');
+    } else {
+      console.log('  Table hunk_summaries already exists');
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_hunk_summaries_review ON hunk_summaries(review_id)');
+    console.log('Migration to schema version 47 complete');
+  },
+
+  48: (db) => {
+    console.log('Running migration to schema version 48: Add tours table...');
+    if (!tableExists(db, 'tours')) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS tours (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          review_id INTEGER NOT NULL UNIQUE,
+          stops TEXT NOT NULL,
+          diff_hash TEXT NOT NULL,
+          provider TEXT,
+          model TEXT,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE
+        )
+      `);
+      console.log('  Created tours table');
+    } else {
+      console.log('  Table tours already exists');
+    }
+    console.log('Migration to schema version 48 complete');
   }
 };
 
@@ -5546,6 +5627,204 @@ class ContextFileRepository {
   }
 }
 
+/**
+ * HunkSummaryRepository class for managing per-hunk natural-language summary
+ * records. Summaries are generated by background AI jobs and keyed by content
+ * hash so that unchanged hunks don't get re-enqueued across reloads.
+ *
+ * Trivial hunks (whitespace, imports, version bumps, etc.) are persisted with
+ * `summary_text = NULL` and a non-null `trivial_reason` so the missing-hash
+ * lookup treats them as "already known, don't re-enqueue". The frontend hides
+ * trivial rows.
+ */
+class HunkSummaryRepository {
+  /**
+   * Create a new HunkSummaryRepository instance
+   * @param {Database} db - Database instance
+   */
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Get all hunk summary rows for a review, ordered by file_path then id
+   * @param {number} reviewId - Review ID
+   * @returns {Promise<Array<Object>>} Array of hunk summary rows
+   */
+  async getByReview(reviewId) {
+    return query(
+      this.db,
+      'SELECT * FROM hunk_summaries WHERE review_id = ? ORDER BY file_path, id',
+      [reviewId]
+    );
+  }
+
+  /**
+   * Get all hunk summary rows for a review scoped to a single file path,
+   * ordered by id.
+   * @param {number} reviewId - Review ID
+   * @param {string} filePath - File path to scope to
+   * @returns {Promise<Array<Object>>} Array of hunk summary rows
+   */
+  async getByReviewAndFile(reviewId, filePath) {
+    return query(
+      this.db,
+      'SELECT * FROM hunk_summaries WHERE review_id = ? AND file_path = ? ORDER BY id',
+      [reviewId, filePath]
+    );
+  }
+
+  /**
+   * Get hunk summary rows for a specific set of content hashes within a review.
+   * Used to identify which hashes already have persisted summaries and which
+   * still need to be enqueued.
+   * @param {number} reviewId - Review ID
+   * @param {Array<string>} hashes - Content hashes to look up
+   * @returns {Promise<Array<Object>>} Array of matching hunk summary rows
+   */
+  async getByHashes(reviewId, hashes) {
+    if (!Array.isArray(hashes) || hashes.length === 0) {
+      return [];
+    }
+    const placeholders = hashes.map(() => '?').join(',');
+    return query(
+      this.db,
+      `SELECT * FROM hunk_summaries WHERE review_id = ? AND content_hash IN (${placeholders})`,
+      [reviewId, ...hashes]
+    );
+  }
+
+  /**
+   * Insert or update many hunk summary rows in a single transaction.
+   * On conflict by (review_id, content_hash), the existing row's mutable
+   * fields are overwritten.
+   * @param {Array<Object>} rows - Rows to upsert. Each row should have
+   *   {review_id, file_path, content_hash, summary_text?, trivial_reason?, provider?, model?}
+   * @returns {Promise<number>} Number of rows processed
+   */
+  async upsertMany(rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+      return 0;
+    }
+    return withTransaction(this.db, () => {
+      const stmt = this.db.prepare(`
+        INSERT INTO hunk_summaries (
+          review_id, file_path, content_hash, summary_text, trivial_reason, provider, model
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(review_id, content_hash) DO UPDATE SET
+          file_path = excluded.file_path,
+          summary_text = excluded.summary_text,
+          trivial_reason = excluded.trivial_reason,
+          provider = excluded.provider,
+          model = excluded.model
+      `);
+      let count = 0;
+      for (const row of rows) {
+        if (row.summary_text == null && row.trivial_reason == null) {
+          throw new Error(
+            `HunkSummaryRepository.upsertMany: row must set summary_text or trivial_reason ` +
+            `(review_id=${row.review_id}, content_hash=${row.content_hash})`
+          );
+        }
+        stmt.run(
+          row.review_id,
+          row.file_path,
+          row.content_hash,
+          row.summary_text ?? null,
+          row.trivial_reason ?? null,
+          row.provider ?? null,
+          row.model ?? null
+        );
+        count++;
+      }
+      return count;
+    });
+  }
+
+  /**
+   * Delete all hunk summary rows for a review
+   * @param {number} reviewId - Review ID
+   * @returns {Promise<Object>} Run result with `changes` count
+   */
+  async deleteByReview(reviewId) {
+    return run(this.db, 'DELETE FROM hunk_summaries WHERE review_id = ?', [reviewId]);
+  }
+}
+
+/**
+ * TourRepository class for managing per-review guided-tour records. A tour is
+ * a single ordered narrative walkthrough (a JSON array of stops). `diff_hash`
+ * is a 16-char SHA-256 prefix of the diff text; the tour-generator uses it to
+ * detect staleness (when the diff changes, the tour is regenerated).
+ *
+ * One row per review (review_id is UNIQUE). On regeneration, upsert replaces
+ * the existing row.
+ */
+class TourRepository {
+  /**
+   * Create a new TourRepository instance
+   * @param {Database} db - Database instance
+   */
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Get the tour row for a review.
+   * `stops` is returned as a raw JSON string; the caller parses.
+   * @param {number} reviewId - Review ID
+   * @returns {Promise<Object|undefined>} The tour row or undefined if none
+   */
+  async get(reviewId) {
+    return queryOne(
+      this.db,
+      'SELECT * FROM tours WHERE review_id = ?',
+      [reviewId]
+    );
+  }
+
+  /**
+   * Insert or replace the tour row for a review. `stops` is stored verbatim;
+   * the caller is responsible for JSON.stringify.
+   * @param {Object} row - { review_id, stops, diff_hash, provider?, model? }
+   * @returns {Promise<Object>} Run result with `changes` count
+   */
+  async upsert(row) {
+    if (row.review_id == null) {
+      throw new Error('TourRepository.upsert: row.review_id is required');
+    }
+    return run(
+      this.db,
+      `
+        INSERT INTO tours (review_id, stops, diff_hash, provider, model)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(review_id) DO UPDATE SET
+          stops = excluded.stops,
+          diff_hash = excluded.diff_hash,
+          provider = excluded.provider,
+          model = excluded.model,
+          created_at = CURRENT_TIMESTAMP
+      `,
+      [
+        row.review_id,
+        row.stops,
+        row.diff_hash,
+        row.provider ?? null,
+        row.model ?? null,
+      ]
+    );
+  }
+
+  /**
+   * Delete the tour row for a review.
+   * @param {number} reviewId - Review ID
+   * @returns {Promise<Object>} Run result with `changes` count
+   */
+  async deleteByReview(reviewId) {
+    return run(this.db, 'DELETE FROM tours WHERE review_id = ?', [reviewId]);
+  }
+}
+
 module.exports = {
   initializeDatabase,
   closeDatabase,
@@ -5571,6 +5850,8 @@ module.exports = {
   GitHubReviewRepository,
   CouncilRepository,
   ContextFileRepository,
+  HunkSummaryRepository,
+  TourRepository,
   generateWorktreeId,
   migrateExistingWorktrees,
   // Exported for testing only

package/src/external/github-adapter.js

@@ -19,7 +19,11 @@
  */
 
 const { GitHubClient, GitHubApiError } = require('../github/client');
-const { getGitHubToken } = require('../config');
+const {
+  getGitHubToken,
+  resolveHostBinding,
+  resolveBindingRepositoryFromPR
+} = require('../config');
 
 const name = 'github';
 
@@ -38,25 +42,74 @@ const credentialEnvVar = 'GITHUB_TOKEN';
  * `GitHubApiError(status: 401)` keeps the existing 401 mapping at the
  * route layer.
  *
+ * Binding-aware: when `repository` (`owner/repo`) is supplied, credential
+ * resolution mirrors `resolveBindingForRequest` in `src/routes/pr.js` —
+ * the repo is resolved to its binding key via `resolveBindingRepositoryFromPR`
+ * and then to a host binding via `resolveHostBinding`, so per-repo
+ * `api_host` / `token` / `token_command` / `features` apply. The
+ * `GitHubClient` is constructed from the FULL binding (not a bare token),
+ * so an alt-host repo routes Octokit's `baseUrl` to its `api_host` instead
+ * of always hitting `api.github.com`.
+ *
+ * When `repository` is absent/empty the no-repo fallback is preserved
+ * exactly: `getGitHubToken(config)` (top-level/env token) + a bare-token
+ * `GitHubClient` (→ `api.github.com`). This keeps any caller without repo
+ * context working unchanged.
+ *
+ * The returned shape also carries `isAltHost` so the route can drive
+ * host-aware comment mapping. On the repo path it reflects the resolved
+ * binding (`Boolean(binding.apiHost)`); on the no-repo fallback it is always
+ * `false` (api.github.com). Alt-hosts don't implement GitHub's deprecated
+ * diff-relative `position` field, so `mapComment` must anchor by `line`
+ * instead — see its docstring.
+ *
  * @param {Object} config - Server config (see `loadConfig()`)
- * @param {Object} [_deps] - Test overrides for { GitHubClient, getGitHubToken }
- * @returns {{ client: Object }}
+ * @param {string} [repository] - "owner/repo" identifier for binding-aware resolution
+ * @param {Object} [_deps] - Test overrides for
+ *   { GitHubClient, getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR }
+ * @returns {{ client: Object, isAltHost: boolean }}
  * @throws {GitHubApiError} with status 401 when no token is configured
  */
-function resolveCredentials(config, _deps) {
+function resolveCredentials(config, repository, _deps) {
   const deps = {
     GitHubClient,
     getGitHubToken,
+    resolveHostBinding,
+    resolveBindingRepositoryFromPR,
     ..._deps
   };
-  const token = deps.getGitHubToken(config || {});
+  const safeConfig = config || {};
+
+  if (repository) {
+    // Binding-aware path. Mirrors resolveBindingForRequest in routes/pr.js:
+    // resolve the PR identity to a binding key, then to a host binding.
+    const [owner, repo] = String(repository).split('/');
+    const bindingRepository = deps.resolveBindingRepositoryFromPR(owner, repo, safeConfig);
+    const binding = deps.resolveHostBinding(bindingRepository, safeConfig);
+    if (!binding || !binding.token) {
+      throw new GitHubApiError(
+        `GitHub token not configured for ${repository}. Set ${credentialEnvVar}, add github_token to ~/.pair-review/config.json, or configure repos["${bindingRepository}"].token / token_command (required for alt-host repos)`,
+        401
+      );
+    }
+    // An api_host on the binding means this repo lives on an alternate Git
+    // host. Surface that so the route can switch mapComment to line-based
+    // anchoring (alt-hosts return position:null with a valid `line`).
+    return { client: new deps.GitHubClient(binding), isAltHost: Boolean(binding.apiHost) };
+  }
+
+  // No-repo fallback — preserved exactly as before so callers without repo
+  // context (top-level/env token → api.github.com) continue to work.
+  const token = deps.getGitHubToken(safeConfig);
   if (!token) {
     throw new GitHubApiError(
       `GitHub token not configured. Set ${credentialEnvVar} or add github_token to ~/.pair-review/config.json`,
       401
     );
   }
-  return { client: new deps.GitHubClient(token) };
+  // The no-repo fallback always targets api.github.com, so it is never an
+  // alt-host — keep the github.com position-based mapping.
+  return { client: new deps.GitHubClient(token), isAltHost: false };
 }
 
 /**
@@ -76,23 +129,40 @@ async function fetchComments({ client, owner, repo, pull_number }) {
 /**
  * Map a raw GitHub review-comment API row to an `external_comments` row.
  *
+ * Host-aware anchoring (the `options.isAltHost` switch):
+ *   - **github.com (default, `isAltHost` falsy)**: `position` is the signal
+ *     for "outdated". A null `position` means the comment no longer maps to
+ *     the current diff, so the current-anchor fields are nulled and
+ *     `original_*` becomes the only authoritative anchor. This path is
+ *     byte-identical to the long-standing behaviour and must not change.
+ *   - **alt-host (`isAltHost === true`)**: alternate Git hosts do NOT
+ *     implement GitHub's DEPRECATED diff-relative `position` field — they
+ *     return `position: null` even for perfectly current comments while
+ *     supplying a valid modern `line`. Keying "outdated" off `position`
+ *     there would discard a good `line` and mis-flag live comments as lost
+ *     anchors. So we anchor uniformly by `line`: a current comment has a
+ *     non-null `line` (`is_outdated = 0`); a genuinely outdated one has
+ *     `line == null` (`is_outdated = 1`, anchored via `original_*`). This
+ *     works whether or not the host also happens to return `position`.
+ *
  * Edge cases handled here (per the phase spec):
  *   - `apiRow.user` is null (deleted account): `author` and `author_url`
  *     both become null. No throw.
- *   - `apiRow.position` is null (outdated): `is_outdated = 1`, current
- *     line/position fields null. `original_*` may still be populated.
- *   - `apiRow.position` AND `apiRow.original_position` both null
- *     (force-push lost anchor): still produces a row — the sync route
- *     decides whether to count or skip. We do NOT throw here.
+ *   - both current AND original anchors null (force-push lost anchor):
+ *     still produces a row — the sync route decides whether to count or
+ *     skip. We do NOT throw here.
  *   - `apiRow.path` missing: throws — `file` is NOT NULL in the schema
  *     and a missing path means upstream gave us something malformed.
  *     Failing early in the mapper is far easier to debug than a SQL
  *     constraint violation deep in an upsert loop.
  *
  * @param {Object} apiRow
+ * @param {Object} [options]
+ * @param {boolean} [options.isAltHost=false] - When true, use line-based
+ *   anchoring (alt-host); when false/omitted, github.com position-based.
  * @returns {Object} A row matching the `external_comments` column names
  */
-function mapComment(apiRow) {
+function mapComment(apiRow, options = {}) {
   if (!apiRow || apiRow.path == null) {
     throw new Error('GitHub adapter: comment missing required field "path"');
   }
@@ -106,19 +176,38 @@ function mapComment(apiRow) {
   }
 
   const user = apiRow.user || null;
-  const positionIsNull = apiRow.position == null;
+  const isAltHost = options.isAltHost === true;
 
-  // When position is null the comment is outdated. GitHub still populates
-  // `line` in many of these responses, but the line number does NOT
-  // correspond to a position in the current diff — using it would create
-  // two conflicting truths (line_end set AND is_outdated=1) and would
-  // make the lost-anchor filter under-count. Force the current-anchor
-  // fields to null so `original_*` is the only authoritative anchor.
-  const line_start = positionIsNull
-    ? null
-    : apiRow.start_line ?? apiRow.line ?? null;
-  const line_end = positionIsNull ? null : apiRow.line ?? null;
-  const diff_position = positionIsNull ? null : apiRow.position ?? null;
+  let line_start;
+  let line_end;
+  let diff_position;
+  let is_outdated;
+
+  if (isAltHost) {
+    // Alt-host: `line` is the authoritative signal. `position` is unreliable
+    // (alt-hosts leave it null even for current comments), so we never null
+    // out a good `line` based on it. `diff_position` is carried through —
+    // legitimately null on most alt-hosts; the frontend renders by
+    // line_start/line_end/side, not by diff_position.
+    const lineIsNull = apiRow.line == null;
+    line_start = lineIsNull ? null : apiRow.start_line ?? apiRow.line ?? null;
+    line_end = lineIsNull ? null : apiRow.line ?? null;
+    diff_position = apiRow.position ?? null;
+    is_outdated = lineIsNull ? 1 : 0;
+  } else {
+    // github.com (unchanged): when position is null the comment is outdated.
+    // GitHub still populates `line` in many of these responses, but the line
+    // number does NOT correspond to a position in the current diff — using
+    // it would create two conflicting truths (line_end set AND is_outdated=1)
+    // and would make the lost-anchor filter under-count. Force the
+    // current-anchor fields to null so `original_*` is the only
+    // authoritative anchor.
+    const positionIsNull = apiRow.position == null;
+    line_start = positionIsNull ? null : apiRow.start_line ?? apiRow.line ?? null;
+    line_end = positionIsNull ? null : apiRow.line ?? null;
+    diff_position = positionIsNull ? null : apiRow.position ?? null;
+    is_outdated = positionIsNull ? 1 : 0;
+  }
 
   return {
     external_id: String(apiRow.id),
@@ -133,7 +222,7 @@ function mapComment(apiRow) {
     line_end,
     diff_position,
     commit_sha: apiRow.commit_id ?? null,
-    is_outdated: positionIsNull ? 1 : 0,
+    is_outdated,
     original_line_start:
       apiRow.original_start_line ?? apiRow.original_line ?? null,
     original_line_end: apiRow.original_line ?? null,

package/src/git/base-branch.js

@@ -8,9 +8,13 @@ const defaults = {
   // This default returns empty so GitHub lookup is silently skipped
   // when no token is provided — never re-resolve config internally.
   getGitHubToken: () => '',
-  createGitHubClient: (token) => {
+  // Callers may optionally pass a binding via _deps.getHostBinding so
+  // alt-host repos route to the configured api_host. The default
+  // returns null which makes the client default to github.com.
+  getHostBinding: () => null,
+  createGitHubClient: (tokenOrBinding) => {
     const { GitHubClient } = require('../github/client');
-    return new GitHubClient(token);
+    return new GitHubClient(tokenOrBinding);
   }
 };
 
@@ -139,11 +143,14 @@ async function tryGitHubPR(repoPath, currentBranch, repository, deps) {
   if (!repository || !repository.includes('/')) return null;
 
   try {
+    // Prefer the host binding (alt-host aware) when callers provide one.
+    // Falls back to the bare token for legacy callers.
+    const binding = deps.getHostBinding();
     const token = deps.getGitHubToken();
-    if (!token) return null;
+    if (!binding && !token) return null;
 
     const [owner, repo] = repository.split('/');
-    const client = deps.createGitHubClient(token);
+    const client = deps.createGitHubClient(binding || token);
     const result = await client.findPRByBranch(owner, repo, currentBranch);
 
     if (result) {