@in-the-loop-labs/pair-review 3.5.1 → 3.6.0

package/src/ai/hunk-hashing.js

@@ -0,0 +1,161 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const crypto = require('crypto');
+
+/**
+ * @typedef {Object} Hunk
+ * @property {string} header - Hunk header line, e.g. "@@ -10,5 +10,7 @@".
+ * @property {string[]} lines - Diff lines including their leading marker
+ *   ('+', '-', ' ', or the literal '\' marker).
+ */
+
+const LOCKFILE_BASENAMES = new Set([
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'Cargo.lock',
+  'Pipfile.lock',
+  'poetry.lock',
+  'composer.lock',
+  'go.sum'
+]);
+
+const JS_TS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const PYTHON_EXTENSIONS = new Set(['.py']);
+
+const JS_IMPORT_PATTERN = /^(?:import\b|from\s+\S+\s+import\b|(?:const|let|var)\s+\w+\s*=\s*require\()/;
+const PY_IMPORT_PATTERN = /^(?:import\b|from\s+\S+\s+import\b)/;
+const PACKAGE_JSON_VERSION_PATTERN = /^"([^"]+)"\s*:\s*"[~^>=<]*\d[\w.\-+*]*"\,?\s*$/;
+
+/**
+ * SHA-256 hex of `${filePath}\n${hunkContent}`.
+ * @param {string} filePath
+ * @param {string} hunkContent
+ * @returns {string}
+ */
+function hashHunk(filePath, hunkContent) {
+  return crypto.createHash('sha256').update(`${filePath}\n${hunkContent}`).digest('hex');
+}
+
+function getExtension(filePath) {
+  const slash = filePath.lastIndexOf('/');
+  const base = slash === -1 ? filePath : filePath.slice(slash + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return '';
+  return base.slice(dot).toLowerCase();
+}
+
+function getBasename(filePath) {
+  const slash = filePath.lastIndexOf('/');
+  return slash === -1 ? filePath : filePath.slice(slash + 1);
+}
+
+function classifyLines(lines) {
+  const added = [];
+  const removed = [];
+  for (const line of lines) {
+    if (line.startsWith('\\')) continue;
+    if (line.startsWith('+')) added.push(line.slice(1));
+    else if (line.startsWith('-')) removed.push(line.slice(1));
+  }
+  return { added, removed };
+}
+
+function isImportOnlyReorder(added, removed, ext) {
+  let pattern;
+  if (JS_TS_EXTENSIONS.has(ext)) pattern = JS_IMPORT_PATTERN;
+  else if (PYTHON_EXTENSIONS.has(ext)) pattern = PY_IMPORT_PATTERN;
+  else return false;
+
+  if (added.length === 0 && removed.length === 0) return false;
+
+  const addedTrimmed = added.map((l) => l.trim());
+  const removedTrimmed = removed.map((l) => l.trim());
+
+  for (const line of addedTrimmed) {
+    if (!pattern.test(line)) return false;
+  }
+  for (const line of removedTrimmed) {
+    if (!pattern.test(line)) return false;
+  }
+
+  if (addedTrimmed.length !== removedTrimmed.length) return false;
+  const a = [...addedTrimmed].sort();
+  const r = [...removedTrimmed].sort();
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== r[i]) return false;
+  }
+  return true;
+}
+
+function extractPackageJsonVersionKey(line) {
+  const match = PACKAGE_JSON_VERSION_PATTERN.exec(line);
+  return match ? match[1] : null;
+}
+
+function isVersionBumpChange(added, removed, basename) {
+  if (basename !== 'package.json' && !LOCKFILE_BASENAMES.has(basename)) return false;
+  if (added.length === 0 && removed.length === 0) return false;
+
+  if (LOCKFILE_BASENAMES.has(basename)) return true;
+
+  const addedKeys = [];
+  for (const line of added) {
+    const key = extractPackageJsonVersionKey(line.trim());
+    if (key === null) return false;
+    addedKeys.push(key);
+  }
+  const removedKeys = [];
+  for (const line of removed) {
+    const key = extractPackageJsonVersionKey(line.trim());
+    if (key === null) return false;
+    removedKeys.push(key);
+  }
+
+  if (addedKeys.length !== removedKeys.length) return false;
+  const a = [...addedKeys].sort();
+  const r = [...removedKeys].sort();
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== r[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Classify a hunk as trivial under one of several heuristics.
+ *
+ * Callers that need generated-file detection should pass
+ *   isGeneratedFile: parser.isGenerated.bind(parser)
+ * where `parser` is the result of
+ *   await getGeneratedFilePatterns(worktreePath)
+ * from src/git/gitattributes.js. When `isGeneratedFile` is omitted, the
+ * generated-file rule is skipped silently.
+ * @param {Hunk} hunk
+ * @param {string} filePath
+ * @param {{ isGeneratedFile?: (filePath: string) => boolean }} [options]
+ * @returns {{ trivial: boolean, reason?: 'imports'|'version_bump'|'generated' }}
+ */
+function isTrivialHunk(hunk, filePath, options) {
+  const opts = options || {};
+
+  if (typeof opts.isGeneratedFile === 'function' && opts.isGeneratedFile(filePath) === true) {
+    return { trivial: true, reason: 'generated' };
+  }
+
+  const lines = hunk && Array.isArray(hunk.lines) ? hunk.lines : [];
+  const { added, removed } = classifyLines(lines);
+
+  const ext = getExtension(filePath);
+  if (isImportOnlyReorder(added, removed, ext)) {
+    return { trivial: true, reason: 'imports' };
+  }
+
+  const basename = getBasename(filePath);
+  if (isVersionBumpChange(added, removed, basename)) {
+    return { trivial: true, reason: 'version_bump' };
+  }
+
+  return { trivial: false };
+}
+
+module.exports = { hashHunk, isTrivialHunk };

package/src/ai/index.js

@@ -13,6 +13,7 @@ const {
   registerProvider,
   getProviderClass,
   getRegisteredProviderIds,
+  resolveNonExecutableProviderId,
   getAllProvidersInfo,
   createProvider,
   testProviderAvailability,
@@ -60,6 +61,7 @@ module.exports = {
   registerProvider,
   getProviderClass,
   getRegisteredProviderIds,
+  resolveNonExecutableProviderId,
   getAllProvidersInfo,
 
   // Factory

package/src/ai/opencode-provider.js

@@ -18,6 +18,7 @@ const logger = require('../utils/logger');
 const { extractJSON } = require('../utils/json-extractor');
 const { CancellationError, isAnalysisCancelled } = require('../routes/shared');
 const { StreamParser, parseOpenCodeLine } = require('./stream-parser');
+const { wireAbortToChild, makeAbortError } = require('./abort-signal-wiring');
 
 // Directory containing bin scripts (git-diff-lines, etc.)
 const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
@@ -102,7 +103,7 @@ class OpenCodeProvider extends AIProvider {
    */
   async execute(prompt, options = {}) {
     return new Promise((resolve, reject) => {
-      const { cwd = process.cwd(), timeout = 300000, level = 'unknown', analysisId, registerProcess, onStreamEvent, logPrefix } = options;
+      const { cwd = process.cwd(), timeout = 300000, level = 'unknown', analysisId, registerProcess, onStreamEvent, logPrefix, abortSignal } = options;
 
       const levelPrefix = logPrefix || `[Level ${level}]`;
       logger.info(`${levelPrefix} Executing OpenCode CLI...`);
@@ -128,7 +129,8 @@ class OpenCodeProvider extends AIProvider {
           ...this.extraEnv,
           PATH: `${BIN_DIR}:${process.env.PATH}`
         },
-        shell: this.useShell
+        shell: this.useShell,
+        detached: this.useShell
       });
 
       const pid = opencode.pid;
@@ -140,6 +142,9 @@ class OpenCodeProvider extends AIProvider {
         logger.info(`${levelPrefix} Registered process ${pid} for analysis ${analysisId}`);
       }
 
+      // Wire AbortSignal -> SIGTERM for tour/summary cancellation.
+      const abortWiring = wireAbortToChild(opencode, abortSignal, { logPrefix: levelPrefix, shell: this.useShell });
+
       let stdout = '';
       let stderr = '';
       let timeoutId = null;
@@ -151,6 +156,7 @@ class OpenCodeProvider extends AIProvider {
         if (settled) return;
         settled = true;
         if (timeoutId) clearTimeout(timeoutId);
+        abortWiring.detach();
         fn(value);
       };
 
@@ -201,11 +207,20 @@ class OpenCodeProvider extends AIProvider {
       opencode.on('close', (code) => {
         if (settled) return;  // Already settled by timeout or error
 
+        // Detach is centralized in `settle`.
+
         // Flush any remaining stream parser buffer
         if (streamParser) {
           streamParser.flush();
         }
 
+        // BackgroundQueue-driven cancellation — mirror of claude-provider.
+        if (abortWiring.cancelled()) {
+          logger.info(`${levelPrefix} OpenCode CLI terminated by user cancel (exit code ${code})`);
+          settle(reject, makeAbortError(`${levelPrefix} Cancelled by user`));
+          return;
+        }
+
         // Check for cancellation signals (SIGTERM=143, SIGKILL=137)
         const isCancellationCode = code === 143 || code === 137;
         if (isCancellationCode && analysisId && isAnalysisCancelled(analysisId)) {
@@ -281,6 +296,7 @@ class OpenCodeProvider extends AIProvider {
 
       // Handle errors
       opencode.on('error', (error) => {
+        // Detach happens inside `settle`.
         if (error.code === 'ENOENT') {
           logger.error(`${levelPrefix} OpenCode CLI not found. Please ensure OpenCode CLI is installed.`);
           settle(reject, new Error(`${levelPrefix} OpenCode CLI not found. ${OpenCodeProvider.getInstallInstructions()}`));
@@ -491,7 +507,7 @@ class OpenCodeProvider extends AIProvider {
 
       if (textContent) {
         // Try to extract JSON from the accumulated text content
-        const extracted = extractJSON(textContent, level);
+        const extracted = extractJSON(textContent, level, levelPrefix);
         if (extracted.success) {
           return extracted;
         }
@@ -503,12 +519,12 @@ class OpenCodeProvider extends AIProvider {
       }
 
       // No text content found, try extracting JSON directly from stdout
-      const extracted = extractJSON(stdout, level);
+      const extracted = extractJSON(stdout, level, levelPrefix);
       return extracted;
 
     } catch (parseError) {
       // stdout might not be valid JSONL at all, try extracting JSON from it
-      const extracted = extractJSON(stdout, level);
+      const extracted = extractJSON(stdout, level, levelPrefix);
       if (extracted.success) {
         return extracted;
       }

package/src/ai/pi-provider.js

@@ -26,6 +26,7 @@ const logger = require('../utils/logger');
 const { extractJSON } = require('../utils/json-extractor');
 const { CancellationError, isAnalysisCancelled } = require('../routes/shared');
 const { createPiLineParser } = require('./stream-parser');
+const { wireAbortToChild, makeAbortError } = require('./abort-signal-wiring');
 
 // Directory containing bin scripts (git-diff-lines, etc.)
 const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
@@ -430,7 +431,7 @@ function appendPiChunkToLineBuffer(state, chunk, levelPrefix) {
  */
 function finalizePiResponseParsing({ textContent, rawOutput, rawOutputTruncated = false }, level, levelPrefix) {
   if (textContent) {
-    const extracted = extractJSON(textContent, level);
+    const extracted = extractJSON(textContent, level, levelPrefix);
     if (extracted.success) {
       return extracted;
     }
@@ -447,7 +448,7 @@ function finalizePiResponseParsing({ textContent, rawOutput, rawOutputTruncated
     };
   }
 
-  return extractJSON(rawOutput, level);
+  return extractJSON(rawOutput, level, levelPrefix);
 }
 
 class PiProvider extends AIProvider {
@@ -579,7 +580,7 @@ class PiProvider extends AIProvider {
    */
   async execute(prompt, options = {}) {
     return new Promise((resolve, reject) => {
-      const { cwd = process.cwd(), timeout = 900000, level = 'unknown', analysisId, registerProcess, onStreamEvent, logPrefix } = options;
+      const { cwd = process.cwd(), timeout = 900000, level = 'unknown', analysisId, registerProcess, onStreamEvent, logPrefix, abortSignal } = options;
 
       const levelPrefix = logPrefix || `[Level ${level}]`;
       logger.info(`${levelPrefix} Executing Pi CLI...`);
@@ -609,7 +610,8 @@ class PiProvider extends AIProvider {
           ...this.extraEnv,
           PATH: `${BIN_DIR}:${process.env.PATH}`
         },
-        shell: this.useShell
+        shell: this.useShell,
+        detached: this.useShell
       });
 
       // Close stdin immediately — prompt is delivered via @file, but some
@@ -626,6 +628,9 @@ class PiProvider extends AIProvider {
         logger.info(`${levelPrefix} Registered process ${pid} for analysis ${analysisId}`);
       }
 
+      // Wire AbortSignal -> SIGTERM for tour/summary cancellation.
+      const abortWiring = wireAbortToChild(pi, abortSignal, { logPrefix: levelPrefix, shell: this.useShell });
+
       const stderrCapture = {
         head: '',
         tail: '',
@@ -652,6 +657,7 @@ class PiProvider extends AIProvider {
         if (settled) return;
         settled = true;
         if (timeoutId) clearTimeout(timeoutId);
+        abortWiring.detach();
         fn(value);
       };
 
@@ -711,6 +717,15 @@ class PiProvider extends AIProvider {
         cleanupTmpFile();
         if (settled) return;  // Already settled by timeout or error
 
+        // Detach is centralized in `settle`.
+
+        // BackgroundQueue-driven cancellation — mirror of claude-provider.
+        if (abortWiring.cancelled()) {
+          logger.info(`${levelPrefix} Pi CLI terminated by user cancel (exit code ${code})`);
+          settle(reject, makeAbortError(`${levelPrefix} Cancelled by user`));
+          return;
+        }
+
         // Check for cancellation signals (SIGTERM=143, SIGKILL=137)
         const isCancellationCode = code === 143 || code === 137;
         if (isCancellationCode && analysisId && isAnalysisCancelled(analysisId)) {
@@ -810,6 +825,7 @@ class PiProvider extends AIProvider {
       // Handle errors
       pi.on('error', (error) => {
         cleanupTmpFile();
+        // Detach happens inside `settle`.
         if (error.code === 'ENOENT') {
           logger.error(`${levelPrefix} Pi CLI not found. Please ensure Pi CLI is installed.`);
           settle(reject, new Error(`${levelPrefix} Pi CLI not found. ${PiProvider.getInstallInstructions()}`));
@@ -994,7 +1010,7 @@ class PiProvider extends AIProvider {
 
     } catch (parseError) {
       // stdout might not be valid JSONL at all, try extracting JSON from it
-      const extracted = extractJSON(stdout, level);
+      const extracted = extractJSON(stdout, level, levelPrefix);
       if (extracted.success) {
         return extracted;
       }

package/src/ai/prompts/hunk-summary.js

@@ -0,0 +1,199 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Hunk summary prompt builder.
+ *
+ * Pure function that produces the prompt body sent to the background provider
+ * for summarizing one file's worth of diff hunks. Output schema and length
+ * constraints are defined in plans/semantic-hunk-summaries-and-tours.md
+ * ("Prompt Design Notes" -> "Summary prompt contract").
+ */
+
+const MAX_CHANGED_FILES_LISTED = 100;
+
+/**
+ * @typedef {Object} HunkInput
+ * @property {string} header - "@@ -10,5 +10,7 @@" line
+ * @property {string[]} lines - Diff body lines with leading +/-/space markers
+ */
+
+/**
+ * @typedef {Object} SummaryContext
+ * @property {string} filePath - Path of the file being summarized
+ * @property {HunkInput[]} hunks - Hunks to summarize, in file order
+ * @property {string} [prTitle] - Optional PR title or local-review name
+ * @property {string} [prDescription] - Optional PR description
+ * @property {string[]} [changedFiles] - Optional list of all changed-file paths in this review (light context)
+ * @property {string} [cwd] - Optional working directory the agent is running in.
+ *   When provided, the prompt invites bounded read-only file access; the path
+ *   itself is NOT embedded in the prompt. Used purely as a signal flag — when
+ *   omitted, the prompt does not promise read-only access at all.
+ */
+
+/**
+ * Returns true if the value is a non-empty, non-whitespace-only string.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Build the prompt body sent to the background provider for summarizing one
+ * file's worth of hunks. Returns a single string (the full prompt).
+ * @param {SummaryContext} context
+ * @returns {string}
+ */
+function buildHunkSummaryPrompt({ filePath, hunks, prTitle, prDescription, changedFiles, cwd } = {}) {
+  if (!hasText(filePath)) {
+    throw new TypeError('filePath is required');
+  }
+  if (hunks === undefined || hunks === null) {
+    throw new TypeError('hunks is required');
+  }
+  if (!Array.isArray(hunks)) {
+    throw new TypeError('hunks is required');
+  }
+
+  const sections = [];
+
+  sections.push(
+    'You are summarizing changed hunks from a code review. Treat the diff text provided below as the primary source. Do NOT modify files. Do NOT run write commands (rm, mv, git commit, etc.). Produce concise natural-language summaries.'
+  );
+
+  if (hasText(cwd)) {
+    sections.push(
+      [
+        'You have read-only access to the current working directory. The diff is',
+        'your primary source. You MAY consult adjacent code ONLY when it materially',
+        'improves the description of WHAT changed:',
+        '- A symbol introduced/modified in the diff has callers or a definition',
+        '  elsewhere whose existence changes the summary (e.g. "extracts a helper',
+        '  now used by 4 sites" vs "adds a helper").',
+        '- The diff is locally ambiguous about what changed (e.g. a one-line',
+        '  signature change whose meaning depends on the function body not in',
+        '  the hunk).',
+        '',
+        'Budget per file: at most ~5 file reads, ~3 grep calls. Do not browse',
+        'broadly. Do not read tests, fixtures, or generated files unless directly',
+        'relevant. Do not modify any file.',
+        '',
+        'The summary still describes what the DIFF changes, not what the',
+        'surrounding code does. Context informs phrasing; it does not become',
+        'the subject.'
+      ].join('\n')
+    );
+  }
+
+  sections.push(
+    [
+      'Style:',
+      '- 1–3 sentences. Aim for one; use two only when a second sentence adds',
+      '  information the first cannot. Three is rare.',
+      '- Target ~200 characters; hard ceiling 400.',
+      '- State WHAT changed in the diff. Context informs phrasing; it does not',
+      '  become the subject. Do not speculate beyond what code you can see makes',
+      '  unambiguous.',
+      '- For mechanical changes (formatting, trivial rename), say so in one short',
+      '  sentence and stop.',
+      '- Lead with a verb (Adds, Removes, Renames, Refactors, Fixes, Moves,',
+      '  Inlines, Extracts).'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'You MAY return summary: null for a hunk only when ALL of these hold:',
+      '- The change is purely mechanical (whitespace, import reorder, lint fix,',
+      '  trivial rename) AND',
+      '- A reader scanning the diff would learn nothing from a summary.',
+      '',
+      'Default is to summarize. When in doubt, write the summary.'
+    ].join('\n')
+  );
+
+  if (hasText(prTitle) || hasText(prDescription)) {
+    const contextLines = ["Author's stated intent (hint only — verify against the diff):"];
+    if (hasText(prTitle)) {
+      contextLines.push(`  Title: ${prTitle.trim()}`);
+    }
+    if (hasText(prDescription)) {
+      contextLines.push(`  Description: ${prDescription.trim()}`);
+    }
+    sections.push(contextLines.join('\n'));
+
+    sections.push(
+      [
+        "The author's stated intent above is a HINT — useful for orientation and",
+        'vocabulary. It is NOT verified ground truth. The diff is ground truth.',
+        '- Use the description to orient your reading and to choose vocabulary that',
+        '  matches the project (e.g. domain terms).',
+        '- Do NOT repeat or paraphrase the description as the summary.',
+        '- If the diff and the description disagree, describe the diff. Do not',
+        '  paper over the disagreement, and do not editorialize about it — just',
+        '  state what the diff does.',
+        '- If the description is vague, templated, or empty, ignore it entirely.'
+      ].join('\n')
+    );
+  }
+
+  if (Array.isArray(changedFiles) && changedFiles.length > 0) {
+    if (changedFiles.length > MAX_CHANGED_FILES_LISTED) {
+      sections.push(
+        `Changed files in this review: ${changedFiles.length} total (list omitted for length)`
+      );
+    } else {
+      const fileLines = ['Changed files in this review:'];
+      for (const path of changedFiles) {
+        fileLines.push(`  - ${path}`);
+      }
+      sections.push(fileLines.join('\n'));
+    }
+  }
+
+  const hunkBlockLines = [`File: ${filePath}`, 'Hunks (numbered):'];
+  if (hunks.length === 0) {
+    hunkBlockLines.push('(no hunks)');
+  } else {
+    hunks.forEach((hunk, idx) => {
+      const header = hunk && typeof hunk.header === 'string' ? hunk.header : '';
+      const lines = hunk && Array.isArray(hunk.lines) ? hunk.lines : [];
+      hunkBlockLines.push(`[${idx + 1}] ${header}`);
+      if (lines.length > 0) {
+        hunkBlockLines.push(lines.join('\n'));
+      }
+    });
+  }
+  sections.push(hunkBlockLines.join('\n'));
+
+  if (hunks.length === 0) {
+    sections.push(
+      [
+        'There are no hunks to summarize.',
+        'Return ONLY this JSON object:',
+        '{ "summaries": [] }',
+        '',
+        'Do not include any extra fields, explanation, or prose outside the JSON.'
+      ].join('\n')
+    );
+  } else {
+    sections.push(
+      [
+        'Return ONLY a JSON object with this shape:',
+        '{ "summaries": [',
+        '    { "index": 1, "summary": "Adds X to do Y." },',
+        '    { "index": 2, "summary": null }',
+        '] }',
+        '',
+        'Rules:',
+        '- One entry per hunk above; index matches the [N] label.',
+        '- `summary` is `string | null` (null only per the opt-out clause above).',
+        '- Do not include any extra fields, explanation, or prose outside the JSON.'
+      ].join('\n')
+    );
+  }
+
+  return sections.join('\n\n');
+}
+
+module.exports = { buildHunkSummaryPrompt };