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

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 };

package/src/ai/prompts/tour.js

@@ -0,0 +1,232 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Tour prompt builder.
+ *
+ * Pure function that produces the prompt body sent to the background provider
+ * for generating a guided "tour" of a code review. The agent is expected to
+ * actively explore the worktree (read files, run the annotated diff tool,
+ * grep) and choose stops grounded in real code it has read directly.
+ */
+
+const { buildAnalysisLineNumberGuidance } = require('./line-number-guidance');
+
+// What the prompt asks the model for. Trivial diffs may legitimately yield
+// only one or two stops; we don't want to coerce padding.
+const PROMPT_MIN_STOPS = 1;
+// Persistence gate: fewer than this and the result is treated as
+// "not tour-worthy" rather than published.
+const PERSIST_MIN_STOPS = 2;
+const MAX_STOPS = 12;
+const TITLE_MAX = 120;
+// Storage cap. The UI clamps the visible description to ~3 lines and
+// reveals the rest behind a "Show more" toggle, so we can afford to give
+// the model more room than the old 280-char hard cap (which produced
+// visibly mid-sentence truncations the user hated).
+const DESCRIPTION_MAX = 800;
+
+/**
+ * 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 generating a tour.
+ *
+ * The agent is expected to explore the worktree directly (Read, grep, the
+ * annotated diff tool) and ground every stop in real file content.
+ *
+ * @param {Object}   context
+ * @param {string}   [context.prTitle]            Optional PR title or local-review name.
+ * @param {string}   [context.prDescription]      Optional PR description.
+ * @param {string}   context.scriptCommand        Annotated-diff command (e.g. `git-diff-lines --cwd "/abs"`).
+ * @param {string[]} context.changedFiles         Repo-relative paths of files in the diff.
+ * @param {string}   [context.worktreePath]       Informational; the agent's cwd.
+ * @returns {string} The full prompt.
+ */
+function buildTourPrompt({
+  prTitle,
+  prDescription,
+  scriptCommand,
+  changedFiles,
+  worktreePath
+} = {}) {
+  if (!hasText(scriptCommand)) {
+    throw new TypeError('scriptCommand is required');
+  }
+  if (!Array.isArray(changedFiles)) {
+    throw new TypeError('changedFiles is required');
+  }
+
+  const sections = [];
+
+  sections.push(
+    [
+      'You are building a guided tour of a pull request or local code change.',
+      'The tour exists for ONE reason: accelerated understanding of the change',
+      'for the reader.',
+      '',
+      'Audience: a reviewer who needs to build an accurate mental model of',
+      'the change fast and know where to focus scrutiny before deciding',
+      'whether to approve, push back, or dig deeper.',
+      '',
+      'Success looks like: after reading the tour in order, the reviewer',
+      '(a) understands what changed and why, and (b) knows which parts',
+      'deserve careful attention.',
+      '',
+      'This is NOT a changelog or a hunk-by-hunk summary. Skip anything a',
+      'competent reviewer absorbs at a glance. Privilege load-bearing logic,',
+      'contract changes, and subtle risk over breadth of coverage.',
+      '',
+      'You have shell tools (Read, the annotated diff tool, cat, grep).',
+      'EXPLORE the worktree directly. Ground every stop in real file content',
+      'you have read. Do NOT modify files. Do NOT run write commands.'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Return ONLY a JSON object with this shape:',
+      '{',
+      '  "stops": [',
+      '    {',
+      '      "file_path": "src/foo.ts",',
+      '      "side": "RIGHT",',
+      '      "line_start": 42,',
+      '      "line_end": 58,',
+      `      "title": "<= ${TITLE_MAX} chars",`,
+      `      "description": "1-3 sentences; aim for ~200-300 chars, up to ${DESCRIPTION_MAX}"`,
+      '    }',
+      '  ]',
+      '}',
+      '',
+      '`side` is "LEFT" or "RIGHT".'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Style:',
+      `- title: a short noun phrase, <= ${TITLE_MAX} characters.`,
+      `- description: 1–3 sentences. Aim for ~200–300 characters; up to ${DESCRIPTION_MAX}`,
+      '  if more context is genuinely needed. Explain WHY this stop matters and',
+      '  what to look for. Do NOT restate what the code does; say why it is load-bearing.',
+      '- Be concrete. No fluff like "this is important code".'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Stop selection:',
+      '- Order stops as a coherent reading path — start with the most load-bearing',
+      '  change, then dependents, then supporting changes. Order does NOT have to',
+      '  follow file order.',
+      '- Skip mechanical/uninteresting code (formatting, imports, whitespace).',
+      '  Include only stops a reviewer benefits from reading explicitly.',
+      '- `[line_start, line_end]` should be tight — a function, a block, a few',
+      '  related lines — not an entire file.',
+      `- Return as many stops as the diff genuinely warrants, up to ${MAX_STOPS}.`,
+      '  Trivial diffs may legitimately yield only 1-2 stops; do not pad. Fewer',
+      '  well-chosen stops beat a long laundry list.',
+      '- Stops must not overlap. Pick the single most informative range per',
+      '  region; do not return multiple stops covering the same function or',
+      '  block under different framings.'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Every stop MUST point at lines that actually changed in the diff:',
+      '- The chosen `[line_start, line_end]` range MUST intersect changed',
+      '  lines for the chosen `side` in the chosen file.',
+      '- Stops on unchanged code or on files outside the diff will be rejected.',
+      '- If you want to call out unchanged code that the change interacts with,',
+      '  pick a stop on a changed line nearby and reference the unchanged code',
+      '  in the description text.'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Side semantics:',
+      '- `RIGHT` = post-change content (added or context lines, by NEW line numbers).',
+      '- `LEFT` = pre-change content (deleted lines, by OLD line numbers). Use only',
+      '  when calling out something that was removed.',
+      '- The range must intersect a changed-line region on the chosen side. Use the',
+      '  annotated diff tool to confirm.'
+    ].join('\n')
+  );
+
+  sections.push(
+    [
+      'Exploration discipline:',
+      '- Use the annotated diff tool to ground every line number. Treat it as the',
+      '  authoritative source for which lines changed and on which side.',
+      '- Read the relevant files to verify ranges sit on meaningful boundaries',
+      '  (full function, full block) before committing to a stop.'
+    ].join('\n')
+  );
+
+  sections.push(buildAnalysisLineNumberGuidance({ scriptCommand }).trim());
+
+  if (hasText(prTitle) || hasText(prDescription)) {
+    const intentLines = ["Author's stated intent (HINT only — verify against the code):"];
+    if (hasText(prTitle)) {
+      intentLines.push(`  Title: ${prTitle.trim()}`);
+    }
+    if (hasText(prDescription)) {
+      intentLines.push(`  Description: ${prDescription.trim()}`);
+    }
+    sections.push(intentLines.join('\n'));
+
+    sections.push(
+      [
+        "The author's stated intent above is a HINT for orientation and vocabulary.",
+        'It is NOT verified ground truth. The code and diff are ground truth.',
+        '- If the description and the code disagree, follow the code.',
+        '- If the description is vague, templated, or empty, ignore it entirely.'
+      ].join('\n')
+    );
+  }
+
+  const changedFilesBlock = ['Changed files in this diff:'];
+  if (changedFiles.length === 0) {
+    changedFilesBlock.push('  (none)');
+  } else {
+    for (const path of changedFiles) {
+      changedFilesBlock.push(`  - ${path}`);
+    }
+  }
+  changedFilesBlock.push('');
+  changedFilesBlock.push(
+    'Stops MUST be in one of the files above. Stops on other files will be rejected.'
+  );
+  sections.push(changedFilesBlock.join('\n'));
+
+  if (hasText(worktreePath)) {
+    sections.push(`Your working directory is: ${worktreePath}`);
+  }
+
+  sections.push(
+    [
+      'Final output rules:',
+      '- JSON only. No prose, no markdown fences.',
+      '- Validate every range against file bounds and (for changed-file stops)',
+      '  against the annotated diff before returning.'
+    ].join('\n')
+  );
+
+  return sections.join('\n\n');
+}
+
+module.exports = {
+  buildTourPrompt,
+  TOUR_PROMPT_MIN_STOPS: PROMPT_MIN_STOPS,
+  TOUR_PERSIST_MIN_STOPS: PERSIST_MIN_STOPS,
+  TOUR_MAX_STOPS: MAX_STOPS,
+  TOUR_TITLE_MAX: TITLE_MAX,
+  TOUR_DESCRIPTION_MAX: DESCRIPTION_MAX
+};

package/src/ai/provider.js

@@ -300,7 +300,7 @@ ${rawResponse}
         }
 
         // Use the generic extractJSON for all providers - the LLM should return raw JSON
-        const extracted = extractJSON(stdout, level);
+        const extracted = extractJSON(stdout, level, levelPrefix);
         if (extracted.success) {
           logger.success(`${levelPrefix} LLM extraction successful`);
           settle(extracted);
@@ -604,6 +604,25 @@ function getRegisteredProviderIds() {
   return Array.from(providerRegistry.keys());
 }
 
+/**
+ * Resolve a non-executable provider id, preferring `preferredId` if it is
+ * non-executable. Falls back to the first registered non-executable provider.
+ * Returns null if none are available.
+ * @param {string} [preferredId] - Preferred provider id
+ * @returns {string|null}
+ */
+function resolveNonExecutableProviderId(preferredId) {
+  if (preferredId) {
+    const cls = getProviderClass(preferredId);
+    if (cls && !cls.isExecutable) return preferredId;
+  }
+  for (const pid of getRegisteredProviderIds()) {
+    const cls = getProviderClass(pid);
+    if (cls && !cls.isExecutable) return pid;
+  }
+  return null;
+}
+
 /**
  * Merge config-override models with a provider's built-in models.
  * Config models with matching IDs replace built-ins; config models with new IDs
@@ -768,6 +787,7 @@ module.exports = {
   registerProvider,
   getProviderClass,
   getRegisteredProviderIds,
+  resolveNonExecutableProviderId,
   getAllProvidersInfo,
   createProvider,
   testProviderAvailability,