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

package/src/routes/pr.js

@@ -25,7 +25,8 @@ const Analyzer = require('../ai/analyzer');
 const { v4: uuidv4 } = require('uuid');
 const fs = require('fs').promises;
 const path = require('path');
-const { getGitHubToken, getWorktreeDisplayName, resolveLoadSkills, buildCouncilProviderOverrides, getRepoSkipBulkFetch } = require('../config');
+const { getGitHubToken, getWorktreeDisplayName, resolveLoadSkills, buildCouncilProviderOverrides, getRepoSkipBulkFetch, getSummaryEnabled, getTourEnabled } = require('../config');
+const { backgroundQueue } = require('../ai/background-queue');
 const logger = require('../utils/logger');
 const { buildDiffLineSet } = require('../utils/diff-annotator');
 const { broadcastReviewEvent } = require('../events/review-events');
@@ -34,6 +35,8 @@ const { buildReviewStartedPayload, buildReviewLoadedPayload, buildAnalysisStarte
 const simpleGit = require('simple-git');
 const { GIT_DIFF_FLAGS_ARRAY, GIT_DIFF_SUMMARY_FLAGS_ARRAY } = require('../git/diff-flags');
 const { walkPRStack, DEFAULT_TRUNK_BRANCHES } = require('../github/stack-walker');
+const summaryGenerator = require('../ai/summary-generator');
+const tourGenerator = require('../ai/tour-generator');
 const {
   activeAnalyses,
   reviewToAnalysisId,
@@ -45,7 +48,9 @@ const {
   registerProcess: registerProcessForCancellation
 } = require('./shared');
 const { safeParseJson } = require('../utils/safe-parse-json');
-const { mergeChangedFilesWithDiff } = require('../utils/diff-file-list');
+const { mergeChangedFilesWithDiff, parseUnifiedDiffPatches } = require('../utils/diff-file-list');
+const { parseHunks } = require('../utils/diff-hunks');
+const { hashHunk } = require('../ai/hunk-hashing');
 const { resolveOriginalFileContentSpecs } = require('../utils/diff-file-content');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
@@ -56,6 +61,57 @@ const analysesRouter = require('./analyses');
 const { worktreeLock } = require('../git/worktree-lock');
 const router = express.Router();
 
+/**
+ * Compute per-file hunk hashes from a canonical (unfiltered) unified diff.
+ * Returns a Map<filePath, string[]> where the array is parallel to the order
+ * `parseHunks(filePatch)` returns hunks. The frontend's `parseDiffIntoBlocks`
+ * walks hunks in the same order, so `hunk_hashes[i]` matches `block[i]`.
+ *
+ * This is computed from the canonical (non-whitespace-filtered) diff so that
+ * the resulting hashes always match the keys persisted in `hunk_summaries`.
+ * Even when the rendered patch is `?w=1` (whitespace-filtered), the hashes
+ * stay aligned to the canonical hunks.
+ *
+ * @param {string} canonicalDiff - Full unified diff (NOT whitespace-filtered)
+ * @returns {Map<string, string[]>}
+ */
+function computeHunkHashesFromDiff(canonicalDiff) {
+  const result = new Map();
+  if (!canonicalDiff) return result;
+  const filePatchMap = parseUnifiedDiffPatches(canonicalDiff);
+  for (const [filePath, filePatch] of filePatchMap.entries()) {
+    const hunks = parseHunks(filePatch);
+    const hashes = hunks.map((h) => hashHunk(filePath, `${h.header}\n${h.lines.join('\n')}`));
+    result.set(filePath, hashes);
+  }
+  return result;
+}
+
+/**
+ * Decorate a `changed_files` array with a parallel `hunk_hashes` array per
+ * file. Hashes come from the canonical diff so they remain stable across
+ * whitespace-filtered renders.
+ *
+ * @param {Array<object>} changedFiles
+ * @param {string} canonicalDiff
+ * @returns {Array<object>} New array; inputs are not mutated.
+ */
+function attachHunkHashes(changedFiles, canonicalDiff) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return changedFiles;
+  const hashes = computeHunkHashesFromDiff(canonicalDiff);
+  return changedFiles.map((file) => {
+    if (typeof file === 'string') return file;
+    const filePath = file?.file;
+    if (!filePath) return file;
+    const fileHashes = hashes.get(filePath);
+    if (!fileHashes) return file;
+    return { ...file, hunk_hashes: fileHashes };
+  });
+}
+
+module.exports._computeHunkHashesFromDiff = computeHunkHashesFromDiff;
+module.exports._attachHunkHashes = attachHunkHashes;
+
 /**
  * Sync pending draft review from GitHub with local database
  *
@@ -254,8 +310,13 @@ router.get('/api/pr/:owner/:repo/:number', async (req, res) => {
       }
     }
 
-    // Prepare response
-    const changedFiles = mergeChangedFilesWithDiff(extendedData.changed_files || [], extendedData.diff || '');
+    // Prepare response. Hunk hashes are computed from the canonical diff so
+    // they remain stable across whitespace-filtered renders (the rendered
+    // patch may be filtered, but the persisted hash keys are not).
+    const changedFiles = attachHunkHashes(
+      mergeChangedFilesWithDiff(extendedData.changed_files || [], extendedData.diff || ''),
+      extendedData.diff || ''
+    );
 
     // Use review.id instead of prMetadata.id to avoid ID collision with local mode
     const response = {
@@ -314,6 +375,40 @@ router.get('/api/pr/:owner/:repo/:number', async (req, res) => {
       }).catch(err => { logger.warn(`Review hook failed: ${err.message}`); });
     }
 
+    (async () => {
+      const reviewContext = {
+        prTitle: prMetadata.title,
+        prDescription: prMetadata.description,
+        changedFiles: changedFiles.map((f) => (typeof f === 'string' ? f : (f.filename || f.file || f.path))).filter(Boolean)
+      };
+      const results = await Promise.allSettled([
+        summaryGenerator.kickOffSummaryJob({
+          db,
+          config,
+          reviewId: review.id,
+          diffText: extendedData.diff,
+          worktreePath: extendedData.worktree_path,
+          reviewContext,
+          trigger: 'auto'
+        }),
+        tourGenerator.kickOffTourJob({
+          db,
+          config,
+          reviewId: review.id,
+          diffText: extendedData.diff,
+          worktreePath: extendedData.worktree_path,
+          reviewContext,
+          trigger: 'auto'
+        })
+      ]);
+      const labels = ['Hunk summary', 'Tour'];
+      results.forEach((r, i) => {
+        if (r.status === 'rejected') {
+          logger.warn(`${labels[i]} kickoff failed for review ${review.id}: ${r.reason?.message || r.reason}`);
+        }
+      });
+    })().catch((err) => logger.warn(`Background AI kickoff failed for review ${review.id}: ${err.message}`));
+
   } catch (error) {
     console.error('Error fetching PR data:', error);
     res.status(500).json({
@@ -506,6 +601,35 @@ router.post('/api/pr/:owner/:repo/:number/refresh', async (req, res) => {
 
     res.json(response);
 
+    // Re-kick the summary and tour jobs against the freshly-refreshed diff.
+    // The frontend's refreshPR() calls this POST then GETs /diff (which is a
+    // read-only endpoint and does NOT enqueue), so without an explicit
+    // kickoff here the in-flight stale job would keep burning tokens until
+    // it completes. Each kickoff is dedup'd by diff digest/hash; when the
+    // diff actually changed (new PR HEAD), the kickoffs auto-cancel the
+    // stale in-flight job before enqueueing the fresh one.
+    (async () => {
+      const reviewContext = {
+        prTitle: prMetadata.title,
+        prDescription: prMetadata.description,
+        changedFiles: (changedFiles || []).map((f) => (typeof f === 'string' ? f : (f.filename || f.file || f.path))).filter(Boolean)
+      };
+      const results = await Promise.allSettled([
+        summaryGenerator.kickOffSummaryJob({
+          db, config, reviewId: review.id, diffText: extendedData.diff, worktreePath: extendedData.worktree_path, reviewContext, trigger: 'auto'
+        }),
+        tourGenerator.kickOffTourJob({
+          db, config, reviewId: review.id, diffText: extendedData.diff, worktreePath: extendedData.worktree_path, reviewContext, trigger: 'auto'
+        })
+      ]);
+      const labels = ['Hunk summary', 'Tour'];
+      results.forEach((r, i) => {
+        if (r.status === 'rejected') {
+          logger.warn(`${labels[i]} kickoff failed for review ${review.id} on refresh: ${r.reason?.message || r.reason}`);
+        }
+      });
+    })().catch((err) => logger.warn(`Background AI kickoff failed for review ${review.id} on refresh: ${err.message}`));
+
   } catch (error) {
     logger.error('Error refreshing PR:', error);
     res.status(500).json({
@@ -514,6 +638,122 @@ router.post('/api/pr/:owner/:repo/:number/refresh', async (req, res) => {
   }
 });
 
+/**
+ * POST /api/pr/:owner/:repo/:number/jobs/:jobKey/start
+ *
+ * Manually trigger a summary or tour generation job for this PR. Used by the
+ * frontend when `auto_generate` is off and the user clicks the toolbar button.
+ *
+ * Mirrors the server-side kickoff that runs on PR load, but passes
+ * `trigger: 'manual'` so it bypasses the `auto_generate` gate (the `enabled`
+ * gate still applies — disabled features return 409).
+ *
+ * Request:
+ *   - `jobKey` path param: `summary` or `tour`
+ *
+ * Responses:
+ *   - 200 `{ started: true,  alreadyRunning: false }` — enqueued
+ *   - 200 `{ started: false, alreadyRunning: true  }` — feature on but a job
+ *                                                       is already in flight
+ *                                                       (idempotent no-op)
+ *   - 200 `{ started: false, reason: 'no-diff' }`   — diff is empty
+ *   - 400 `{ error: 'Invalid jobKey' }`             — unknown jobKey
+ *   - 404 `{ error: '...' }`                        — PR not found
+ *   - 409 `{ error: '... disabled' }`               — feature disabled in config
+ */
+const MANUAL_START_JOB_KEYS = new Set(['summary', 'tour']);
+
+router.post('/api/pr/:owner/:repo/:number/jobs/:jobKey/start', async (req, res) => {
+  try {
+    const { owner, repo, number, jobKey } = req.params;
+    const prNumber = parseInt(number, 10);
+
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+      return res.status(400).json({ error: 'Invalid pull request number' });
+    }
+    if (!MANUAL_START_JOB_KEYS.has(jobKey)) {
+      return res.status(400).json({ error: `Invalid jobKey "${jobKey}" (expected "summary" or "tour")` });
+    }
+
+    const repository = normalizeRepository(owner, repo);
+    const db = req.app.get('db');
+    const config = req.app.get('config') || {};
+
+    // Enforce the feature-enabled gate at the HTTP boundary so the frontend
+    // gets a clean 409 instead of a silent no-op from the generator.
+    if (jobKey === 'summary' && !getSummaryEnabled(config)) {
+      return res.status(409).json({ error: 'Summaries feature is disabled in config' });
+    }
+    if (jobKey === 'tour' && !getTourEnabled(config)) {
+      return res.status(409).json({ error: 'Tours feature is disabled in config' });
+    }
+
+    const prMetadata = await queryOne(db, `
+      SELECT id, pr_number, repository, title, description, pr_data
+      FROM pr_metadata
+      WHERE pr_number = ? AND repository = ? COLLATE NOCASE
+    `, [prNumber, repository]);
+
+    if (!prMetadata) {
+      return res.status(404).json({
+        error: `Pull request #${prNumber} not found in repository ${repository}`
+      });
+    }
+
+    const reviewRepo = new ReviewRepository(db);
+    const { review } = await reviewRepo.getOrCreate({ prNumber, repository });
+
+    let extendedData = {};
+    try {
+      extendedData = prMetadata.pr_data ? JSON.parse(prMetadata.pr_data) : {};
+    } catch (parseError) {
+      logger.warn(`Could not parse pr_data for PR #${prNumber}: ${parseError.message}`);
+    }
+
+    const diffText = extendedData.diff || '';
+    const worktreePath = extendedData.worktree_path || null;
+
+    if (!diffText || !worktreePath) {
+      return res.json({ started: false, reason: 'no-diff' });
+    }
+
+    // Idempotency: if a job is already in flight for this review/job-type,
+    // don't double-start. The frontend already has the in-flight event stream.
+    const activeJobType = typeof backgroundQueue.findActiveJobType === 'function'
+      ? backgroundQueue.findActiveJobType(review.id, jobKey === 'summary' ? 'summaries' : 'tour')
+      : null;
+    if (activeJobType) {
+      return res.json({ started: false, alreadyRunning: true });
+    }
+
+    const reviewContext = {
+      prTitle: prMetadata.title,
+      prDescription: prMetadata.description,
+      changedFiles: (extendedData.changed_files || [])
+        .map((f) => (typeof f === 'string' ? f : (f.filename || f.file || f.path)))
+        .filter(Boolean)
+    };
+
+    // Kick off in the background — return the start status immediately so
+    // the frontend can switch the button to its generating state. Errors
+    // are logged but the HTTP response is already sent.
+    if (jobKey === 'summary') {
+      Promise.resolve(summaryGenerator.kickOffSummaryJob({
+        db, config, reviewId: review.id, diffText, worktreePath, reviewContext, trigger: 'manual'
+      })).catch((err) => logger.warn(`Manual hunk summary kickoff failed for review ${review.id}: ${err.message}`));
+    } else {
+      Promise.resolve(tourGenerator.kickOffTourJob({
+        db, config, reviewId: review.id, diffText, worktreePath, reviewContext, trigger: 'manual'
+      })).catch((err) => logger.warn(`Manual tour kickoff failed for review ${review.id}: ${err.message}`));
+    }
+
+    return res.json({ started: true, alreadyRunning: false });
+  } catch (error) {
+    logger.error('Error starting manual job:', error);
+    res.status(500).json({ error: 'Failed to start job: ' + error.message });
+  }
+});
+
 /**
  * Check if PR data is stale (remote has newer commits)
  */
@@ -826,6 +1066,21 @@ router.get('/api/pr/:owner/:repo/:number/diff', async (req, res) => {
       }));
     }
 
+    // Hunk hashes MUST come from the canonical (unfiltered) diff. When
+    // hideWhitespace is on the rendered `diffContent` is the filtered diff,
+    // which would produce hashes that diverge from the keys persisted in
+    // `hunk_summaries`. We deliberately do NOT fall back to `diffContent`:
+    // if `prData.diff` is missing, fail closed and emit no hashes so the
+    // frontend skips anchoring rather than anchoring to misaligned hunks.
+    if (prData.diff) {
+      changedFiles = attachHunkHashes(changedFiles, prData.diff);
+    } else {
+      logger.warn(
+        `[hunk-hash] PR #${prNumber} ${repository}: no canonical prData.diff; ` +
+        'omitting hunk_hashes (summaries will not anchor for this response).'
+      );
+    }
+
     // When diff was regenerated (whitespace), compute aggregate stats from
     // the regenerated changedFiles instead of using stale cached values from prData.
     const additions = hideWhitespace

package/src/routes/reviews.js

@@ -8,11 +8,12 @@
  */
 
 const express = require('express');
-const { query, queryOne, run, withTransaction, CommentRepository, ReviewRepository, AnalysisRunRepository } = require('../database');
+const { query, queryOne, run, withTransaction, CommentRepository, ReviewRepository, AnalysisRunRepository, HunkSummaryRepository, TourRepository } = require('../database');
 const { calculateStats, getStatsQuery } = require('../utils/stats-calculator');
 const { activeAnalyses, reviewToAnalysisId } = require('./shared');
 const logger = require('../utils/logger');
 const { broadcastReviewEvent } = require('../events/review-events');
+const { backgroundQueue } = require('../ai/background-queue');
 const { ensureContextFileForComment } = require('../utils/auto-context');
 const path = require('path');
 const fs = require('fs').promises;
@@ -22,37 +23,10 @@ const { normalizeRepository } = require('../utils/paths');
 const { resolveFormat, formatAdoptedComment: formatComment } = require('../utils/comment-formatter');
 const { safeParseJson } = require('../utils/safe-parse-json');
 const { resolveOriginalFileContentSpecs } = require('../utils/diff-file-content');
+const validateReviewId = require('./middleware/validate-review-id');
 
 const router = express.Router();
 
-/**
- * Middleware: validate that :reviewId exists in the reviews table.
- * Attaches the review record to req.review for downstream handlers.
- */
-async function validateReviewId(req, res, next) {
-  try {
-    const reviewId = parseInt(req.params.reviewId, 10);
-
-    if (isNaN(reviewId) || reviewId <= 0) {
-      return res.status(400).json({ error: 'Invalid review ID' });
-    }
-
-    const db = req.app.get('db');
-    const reviewRepo = new ReviewRepository(db);
-    const review = await reviewRepo.getReview(reviewId);
-
-    if (!review) {
-      return res.status(404).json({ error: `Review #${reviewId} not found` });
-    }
-
-    req.review = review;
-    req.reviewId = reviewId;
-    next();
-  } catch (error) {
-    next(error);
-  }
-}
-
 /**
  * GET /api/reviews/:reviewId/comments
  * Get all comments for a review.
@@ -1070,4 +1044,146 @@ router.get('/api/reviews/:reviewId/file-content/:fileName(*)', validateReviewId,
   }
 });
 
+// ==========================================================================
+// Hunk Summaries Route
+// ==========================================================================
+
+/**
+ * GET /api/reviews/:reviewId/hunk-summaries
+ * Get all hunk summaries for a review (PR or Local).
+ * Returns trivial-marker rows alongside generated summaries; the frontend filters.
+ */
+router.get('/api/reviews/:reviewId/hunk-summaries', validateReviewId, async (req, res) => {
+  try {
+    const db = req.app.get('db');
+    const repo = new HunkSummaryRepository(db);
+    const rows = await repo.getByReview(req.reviewId);
+    // `generating` reflects whether the background queue is still working
+    // on this review's summaries; the frontend uses it to show a "generating"
+    // pulse on the toolbar toggle until `review:background_job_finished`
+    // fires for jobType=`summaries:*`.
+    const generating = backgroundQueue.hasActiveForReview(req.reviewId, 'summaries');
+    res.json({
+      summaries: rows.map((row) => ({
+        file_path: row.file_path,
+        content_hash: row.content_hash,
+        summary_text: row.summary_text,
+        trivial_reason: row.trivial_reason
+      })),
+      generating
+    });
+  } catch (error) {
+    logger.error('Error fetching hunk summaries:', error);
+    res.status(500).json({ error: 'Failed to fetch hunk summaries' });
+  }
+});
+
+// ==========================================================================
+// Tour Route
+// ==========================================================================
+
+/**
+ * GET /api/reviews/:reviewId/tour
+ * Get the persisted guided tour for a review (PR or Local).
+ * Returns `{tour: null}` when no tour has been generated yet, otherwise
+ * returns `{tour: {stops, diff_hash, stale, generating, provider, model, created_at}}`.
+ *
+ * `stale` is true when a `tour` job is currently in flight for this review,
+ * meaning the persisted tour may be about to be replaced. `generating` is
+ * true when there is no persisted tour yet but a job is in flight.
+ */
+router.get('/api/reviews/:reviewId/tour', validateReviewId, async (req, res) => {
+  try {
+    const db = req.app.get('db');
+    const repo = new TourRepository(db);
+    const row = await repo.get(req.reviewId);
+    const generating = backgroundQueue.hasActiveForReview(req.reviewId, 'tour');
+
+    if (!row) {
+      return res.json({ tour: null, generating });
+    }
+
+    let stops;
+    try {
+      stops = JSON.parse(row.stops);
+    } catch (err) {
+      logger.warn(`Failed to parse tour.stops for review ${req.reviewId}: ${err.message}`);
+      return res.status(500).json({ error: 'Tour data corrupt' });
+    }
+
+    res.json({
+      tour: {
+        stops,
+        diff_hash: row.diff_hash,
+        stale: generating,
+        provider: row.provider,
+        model: row.model,
+        created_at: row.created_at
+      },
+      generating
+    });
+  } catch (error) {
+    logger.error('Error fetching tour:', error);
+    res.status(500).json({ error: 'Failed to fetch tour' });
+  }
+});
+
+// ==========================================================================
+// Background Job Cancellation
+// ==========================================================================
+
+// Only these prefixes are user-cancellable. We deliberately do NOT accept
+// arbitrary jobKeys — that would let the UI cancel internal jobs we don't
+// want to be cancellable from the toolbar (e.g. future scheduling work).
+const CANCELLABLE_JOB_PREFIXES = new Set(['tour', 'summaries']);
+
+/**
+ * POST /api/reviews/:reviewId/jobs/:jobKey/cancel
+ *
+ * Cancel an in-flight background job (tour or summaries) for this review.
+ * Aborts the per-job `AbortSignal`, which kills the upstream CLI child
+ * process so we stop burning tokens immediately.
+ *
+ * Works for BOTH Local mode (`/local/:reviewId`) and PR mode (`/pr/...`)
+ * because both modes write into the same `reviews` table and dispatch
+ * jobs through the same `backgroundQueue` keyed by reviewId. The
+ * separate `/api/local/...` cancel route below shares this handler so
+ * the contract stays in one place.
+ *
+ * Request:
+ *   - `jobKey` path param: bare prefix (`tour` | `summaries`) or full
+ *     job key suffix (`summaries:<digest>`). Bare prefix cancels ALL
+ *     matching variants — what the toolbar actually wants.
+ *
+ * Responses:
+ *   - 200 `{ cancelled: true, count: N }`  - aborted N job(s)
+ *   - 404 `{ cancelled: false }`           - nothing in flight
+ *   - 400                                  - invalid jobKey
+ */
+async function handleJobCancel(req, res) {
+  const rawKey = String(req.params.jobKey || '').trim();
+  // Strip whitespace; reject if empty, contains slashes/control chars, or
+  // does not start with an allow-listed prefix. We deliberately do NOT
+  // accept arbitrary keys — see CANCELLABLE_JOB_PREFIXES comment.
+  if (!rawKey || /[/\\\s]/.test(rawKey)) {
+    return res.status(400).json({ error: 'Invalid jobKey' });
+  }
+  const prefix = rawKey.includes(':') ? rawKey.slice(0, rawKey.indexOf(':')) : rawKey;
+  if (!CANCELLABLE_JOB_PREFIXES.has(prefix)) {
+    return res.status(400).json({ error: `jobKey "${prefix}" is not cancellable` });
+  }
+
+  const { cancelled } = backgroundQueue.cancel(req.reviewId, rawKey);
+  if (cancelled === 0) {
+    logger.info(`Cancel request for ${req.reviewId}:${rawKey} matched no in-flight job`);
+    return res.status(404).json({ cancelled: false });
+  }
+  logger.info(`Cancelled ${cancelled} background job(s) for ${req.reviewId}:${rawKey}`);
+  res.json({ cancelled: true, count: cancelled });
+}
+
+router.post('/api/reviews/:reviewId/jobs/:jobKey/cancel', validateReviewId, handleJobCancel);
+
 module.exports = router;
+module.exports.handleJobCancel = handleJobCancel;
+module.exports.CANCELLABLE_JOB_PREFIXES = CANCELLABLE_JOB_PREFIXES;

package/src/utils/diff-hunks.js

@@ -0,0 +1,65 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const { parseUnifiedDiffPatches } = require('./diff-file-list');
+
+/**
+ * @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).
+ */
+
+/**
+ * Split a single file's patch text into per-hunk structures.
+ * @param {string} filePatch - Patch text for one file (with or without diff header).
+ * @returns {Hunk[]} Array of hunks; empty when the patch contains no `@@` lines.
+ */
+function parseHunks(filePatch) {
+  if (!filePatch) return [];
+
+  const lines = filePatch.split('\n');
+  const hunks = [];
+  let current = null;
+
+  for (const line of lines) {
+    if (line.startsWith('@@')) {
+      if (current) hunks.push(current);
+      current = { header: line, lines: [] };
+      continue;
+    }
+    if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  if (current) hunks.push(current);
+
+  for (const hunk of hunks) {
+    while (hunk.lines.length > 0 && hunk.lines[hunk.lines.length - 1] === '') {
+      hunk.lines.pop();
+    }
+  }
+
+  return hunks;
+}
+
+/**
+ * Parse a full unified diff into a Map of file path -> hunks.
+ * @param {string} diffText - Full unified diff text spanning many files.
+ * @returns {Map<string, Hunk[]>} Map keyed by the new path (or old path for deletions).
+ */
+function parseUnifiedDiffHunks(diffText) {
+  const result = new Map();
+  if (!diffText) return result;
+
+  const patches = parseUnifiedDiffPatches(diffText);
+  for (const [filePath, patch] of patches.entries()) {
+    const hunks = parseHunks(patch);
+    if (hunks.length === 0) continue;
+    result.set(filePath, hunks);
+  }
+
+  return result;
+}
+
+module.exports = { parseHunks, parseUnifiedDiffHunks };

package/src/utils/json-extractor.js

@@ -15,10 +15,13 @@ const logger = require('./logger');
  *
  * @param {string} response - Raw response text (may include preamble/postamble prose)
  * @param {string|number} level - Level identifier for logging (e.g., 1, 2, 3, 'orchestration', 'unknown')
+ * @param {string} [logPrefix] - Custom log prefix to use instead of `[Level <level>]`.
+ *   Used by callers (e.g., summary generation, council mode) that have a more
+ *   meaningful identifier than a numeric analysis level.
  * @returns {Object} Extraction result with success flag and data/error
  */
-function extractJSON(response, level = 'unknown') {
-  const levelPrefix = `[Level ${level}]`;
+function extractJSON(response, level = 'unknown', logPrefix) {
+  const levelPrefix = logPrefix || `[Level ${level}]`;
 
   if (!response || !response.trim()) {
     return { success: false, error: 'Empty response' };