@remnic/core 1.1.12 → 1.1.14

package/src/coding/review-context.test.ts

@@ -0,0 +1,316 @@
+/**
+ * Tests for the diff-aware review-context packer (issue #569 PR 4).
+ *
+ * All fixtures synthetic — no real diffs, no real user data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isReviewPrompt,
+  packReviewContext,
+  parseTouchedFiles,
+  rankReviewCandidates,
+  type ReviewCandidate,
+} from "./review-context.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// isReviewPrompt
+// ──────────────────────────────────────────────────────────────────────────
+
+test("isReviewPrompt: matches the #569 keyword list (case-insensitive)", () => {
+  for (const prompt of [
+    "review this PR",
+    "Review this diff",
+    "look at this PR",
+    "what changed?",
+    "WHAT CHANGED in this branch",
+    "can you do a code review?",
+    "what's in this PR?",
+    "what is in this patch?",
+  ]) {
+    assert.equal(isReviewPrompt(prompt), true, `expected match: ${JSON.stringify(prompt)}`);
+  }
+});
+
+test("isReviewPrompt: rejects non-review prompts", () => {
+  for (const prompt of [
+    "how do i set up the project?",
+    "what is the meaning of life",
+    "refactor the foo module",
+    "write a test for bar",
+    "", // empty
+    "   ",
+  ]) {
+    assert.equal(isReviewPrompt(prompt), false, `expected non-match: ${JSON.stringify(prompt)}`);
+  }
+});
+
+test("isReviewPrompt: `reviewer` (longer word) does NOT match `review`", () => {
+  // Whole-word boundary.
+  assert.equal(isReviewPrompt("who is the reviewer on call?"), false);
+});
+
+test("isReviewPrompt: null/undefined input returns false defensively", () => {
+  assert.equal(isReviewPrompt(null), false);
+  assert.equal(isReviewPrompt(undefined), false);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// parseTouchedFiles
+// ──────────────────────────────────────────────────────────────────────────
+
+test("parseTouchedFiles: extracts paths from `diff --git` lines", () => {
+  const diff = [
+    "diff --git a/src/foo.ts b/src/foo.ts",
+    "index 111..222 100644",
+    "--- a/src/foo.ts",
+    "+++ b/src/foo.ts",
+    "@@ -1,3 +1,3 @@",
+    "-old",
+    "+new",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["src/foo.ts"]);
+});
+
+test("parseTouchedFiles: extracts paths from --- / +++ headers when no `diff --git` line", () => {
+  const diff = [
+    "--- a/docs/readme.md",
+    "+++ b/docs/readme.md",
+    "@@ -1 +1 @@",
+    "-old",
+    "+new",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["docs/readme.md"]);
+});
+
+test("parseTouchedFiles: strips `a/` / `b/` prefixes exactly once", () => {
+  const diff = "diff --git a/a/foo.ts b/a/foo.ts";
+  // Path "a/foo.ts" — not "foo.ts". Only the leading single-letter prefix is stripped.
+  assert.deepEqual(parseTouchedFiles(diff), ["a/foo.ts"]);
+});
+
+test("parseTouchedFiles: ignores /dev/null markers (adds and deletes)", () => {
+  const diff = [
+    "diff --git a/new.ts b/new.ts",
+    "new file mode 100644",
+    "--- /dev/null",
+    "+++ b/new.ts",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["new.ts"]);
+});
+
+test("parseTouchedFiles: multi-file diff deduplicates and sorts", () => {
+  const diff = [
+    "diff --git a/z.ts b/z.ts",
+    "--- a/z.ts",
+    "+++ b/z.ts",
+    "diff --git a/a.ts b/a.ts",
+    "--- a/a.ts",
+    "+++ b/a.ts",
+    "diff --git a/m.ts b/m.ts",
+    "--- a/m.ts",
+    "+++ b/m.ts",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["a.ts", "m.ts", "z.ts"]);
+});
+
+test("parseTouchedFiles: empty / non-string / whitespace input → empty list", () => {
+  assert.deepEqual(parseTouchedFiles(""), []);
+  assert.deepEqual(parseTouchedFiles(null), []);
+  assert.deepEqual(parseTouchedFiles(undefined), []);
+  assert.deepEqual(parseTouchedFiles("   \n  "), []);
+});
+
+test("parseTouchedFiles: rename handles both sides of the diff --git line", () => {
+  const diff = [
+    "diff --git a/old/name.ts b/new/name.ts",
+    "similarity index 98%",
+    "rename from old/name.ts",
+    "rename to new/name.ts",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["new/name.ts", "old/name.ts"]);
+});
+
+test("parseTouchedFiles: quoted `diff --git` paths with spaces are kept intact", () => {
+  // Regression: the previous `\\S+` tokenizer shattered
+  // `"a/src/my file.ts" "b/src/my file.ts"` into four half-paths. Quoted
+  // diff-git paths must be parsed as single tokens.
+  //
+  // Real git emits quoted `---` / `+++` headers whenever the filename
+  // contains whitespace, matching the `diff --git` line — so both places
+  // we parse must respect quoting.
+  const diff = [
+    'diff --git "a/src/my file.ts" "b/src/my file.ts"',
+    '--- "a/src/my file.ts"',
+    '+++ "b/src/my file.ts"',
+    "@@ -1 +1 @@",
+    "-old",
+    "+new",
+  ].join("\n");
+  const out = parseTouchedFiles(diff);
+  assert.deepEqual(out, ["src/my file.ts"]);
+});
+
+test("parseTouchedFiles: --- / +++ header alone (no diff --git prefix) handles quoted path", () => {
+  // Regression: the `--- / +++` header regex used `\S+`, which stops at the
+  // first internal whitespace. For quoted paths like `--- "a/foo bar.ts"`
+  // the path was silently truncated after `"a/foo`. Now the header path is
+  // extracted with an explicit tokenizer that respects quotes.
+  const diff = [
+    '--- "a/path with spaces.ts"',
+    '+++ "b/path with spaces.ts"',
+    "@@ -1 +1 @@",
+    "-old",
+    "+new",
+  ].join("\n");
+  assert.deepEqual(parseTouchedFiles(diff), ["path with spaces.ts"]);
+});
+
+test("parseTouchedFiles: quoted paths in --- / +++ headers (stripDiffPathPrefix order)", () => {
+  // Regression: `stripDiffPathPrefix` checked `a/` / `b/` BEFORE stripping
+  // quotes, so `"a/path with spaces.ts"` never matched the prefix, leaving
+  // a bogus `"a/path` entry. Quote-stripping must happen first so the
+  // prefix check sees the unquoted `a/path with spaces.ts`.
+  const diff = [
+    'diff --git "a/path with spaces.ts" "b/path with spaces.ts"',
+    '--- "a/path with spaces.ts"',
+    '+++ "b/path with spaces.ts"',
+  ].join("\n");
+  const out = parseTouchedFiles(diff);
+  assert.deepEqual(out, ["path with spaces.ts"]);
+});
+
+test("parseTouchedFiles: unterminated quoted path does not crash or produce fragments", () => {
+  // Defensive: a malformed diff with an unclosed quote must not throw and
+  // must not emit garbage touched-file entries.
+  const diff = 'diff --git "a/broken src/foo.ts\n';
+  const out = parseTouchedFiles(diff);
+  assert.deepEqual(out, []);
+});
+
+test("parseTouchedFiles: escaped quote inside quoted path is preserved", () => {
+  // Git uses backslash escapes inside C-quoted paths. The parser must
+  // handle `\"` without terminating the token early, and must leave the
+  // unescaped literal quote in the final path.
+  const diff = 'diff --git "a/has\\"quote.ts" "b/has\\"quote.ts"\n';
+  const out = parseTouchedFiles(diff);
+  assert.deepEqual(out, ['has"quote.ts']);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// rankReviewCandidates
+// ──────────────────────────────────────────────────────────────────────────
+
+function c(id: string, score: number, entityRefs?: string[]): ReviewCandidate {
+  return { id, score, entityRefs };
+}
+
+test("rankReviewCandidates: no touched files → no boost; stable by (score desc, id asc)", () => {
+  const out = rankReviewCandidates(
+    [c("b", 0.3), c("a", 0.8), c("c", 0.3)],
+    [],
+  );
+  assert.deepEqual(
+    out.map((r) => r.id),
+    ["a", "b", "c"],
+  );
+  for (const r of out) assert.equal(r.boost, 0);
+});
+
+test("rankReviewCandidates: matched memory floats above same-score unmatched peer", () => {
+  // Two candidates with identical score; only one mentions a touched file.
+  // The match boost must break the tie and push the matched one first.
+  const candidates = [
+    c("same-unrelated", 0.3, ["lib/other.ts"]),
+    c("same-matched", 0.3, ["src/foo.ts"]),
+  ];
+  const out = rankReviewCandidates(candidates, ["src/foo.ts"]);
+  assert.equal(out[0]!.id, "same-matched");
+  assert.equal(out[0]!.boost, 0.5);
+  assert.equal(out[1]!.id, "same-unrelated");
+  assert.equal(out[1]!.boost, 0);
+});
+
+test("rankReviewCandidates: boost narrows gap with stronger unmatched peer (0.1+boost vs 0.7)", () => {
+  // A boosted weak candidate does NOT beat a strong unmatched peer — the
+  // boost is a bias, not a filter. But it should at least close the gap.
+  const candidates = [
+    c("strong-unrelated", 0.7, ["lib/other.ts"]),
+    c("weak-matched", 0.1, ["src/foo.ts"]),
+  ];
+  const out = rankReviewCandidates(candidates, ["src/foo.ts"]);
+  assert.equal(out[0]!.id, "strong-unrelated", "0.7 still wins against 0.1 + 0.5 = 0.6");
+  // But the matched candidate now sits at 0.6 instead of 0.1.
+  const matched = out.find((r) => r.id === "weak-matched");
+  assert.ok(matched);
+  assert.equal(matched!.score + matched!.boost, 0.6);
+});
+
+test("rankReviewCandidates: boost is capped at 1.0 even with many matches", () => {
+  const cand = c("many-hits", 0, ["a.ts", "b.ts", "c.ts", "d.ts", "e.ts"]);
+  const out = rankReviewCandidates([cand], ["a.ts", "b.ts", "c.ts", "d.ts", "e.ts"]);
+  assert.ok(out[0]);
+  assert.equal(out[0]!.boost, 1.0, "boost must cap at MAX_BOOST");
+});
+
+test("rankReviewCandidates: missing entityRefs → boost 0 (no crash)", () => {
+  const out = rankReviewCandidates([{ id: "x", score: 0.5 }], ["src/foo.ts"]);
+  assert.equal(out[0]!.boost, 0);
+});
+
+test("rankReviewCandidates: substring matching — ref 'foo.ts' matches touched 'src/foo.ts'", () => {
+  const out = rankReviewCandidates(
+    [c("basename-ref", 0.1, ["foo.ts"])],
+    ["src/foo.ts"],
+  );
+  assert.equal(out[0]!.boost, 0.5, "basename-style ref should match a repo-relative touched path");
+});
+
+test("rankReviewCandidates: deterministic tie-break by id (rule 19 — comparator returns 0 for equal)", () => {
+  const out = rankReviewCandidates(
+    [c("zeta", 0.5), c("alpha", 0.5), c("mu", 0.5)],
+    [],
+  );
+  assert.deepEqual(
+    out.map((r) => r.id),
+    ["alpha", "mu", "zeta"],
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// packReviewContext end-to-end
+// ──────────────────────────────────────────────────────────────────────────
+
+test("packReviewContext: full path — diff → touched files + ranked recall", () => {
+  const diff = [
+    "diff --git a/src/auth.ts b/src/auth.ts",
+    "--- a/src/auth.ts",
+    "+++ b/src/auth.ts",
+    "@@ -1 +1 @@",
+    "-old",
+    "+new",
+  ].join("\n");
+  const result = packReviewContext({
+    diff,
+    candidates: [
+      c("auth-history", 0.2, ["src/auth.ts"]),
+      c("random-other", 0.6, ["db.sql"]),
+    ],
+  });
+
+  assert.deepEqual(result.touchedFiles, ["src/auth.ts"]);
+  assert.equal(result.rankedRecall[0]!.id, "auth-history");
+  assert.equal(result.rankedRecall[0]!.boost, 0.5);
+  assert.equal(result.rankedRecall[1]!.id, "random-other");
+});
+
+test("packReviewContext: empty diff → no touched files, no boosts, ranked by score", () => {
+  const result = packReviewContext({
+    diff: "",
+    candidates: [c("a", 0.1), c("b", 0.9), c("c", 0.5)],
+  });
+  assert.deepEqual(result.touchedFiles, []);
+  assert.deepEqual(result.rankedRecall.map((r) => r.id), ["b", "c", "a"]);
+});

package/src/coding/review-context.ts

@@ -0,0 +1,349 @@
+/**
+ * Diff-aware review-context packer (issue #569 PR 4).
+ *
+ * When an agent is asked "review this PR" / "what changed in this diff" /
+ * "look at this diff", the prompt that reaches recall is short and generic
+ * — the real signal is the diff itself. This module:
+ *
+ *   1. Detects review-intent prompts via `isReviewPrompt`.
+ *   2. Extracts the touched file list from a unified diff via
+ *      `parseTouchedFiles`.
+ *   3. Re-ranks a set of candidate memories so that memories whose
+ *      `entityRefs` mention a touched path float to the top. The boost is
+ *      additive and bounded so it doesn't obliterate the original ranking —
+ *      it's a bias, not a filter.
+ *
+ * Pure — no orchestrator, no storage. Callers inject the candidate memories
+ * they already have from their normal recall pipeline. This keeps the
+ * module easy to test and integrates cleanly with the existing tiered-recall
+ * code in `orchestrator.ts` (the tier itself can be wired later; the pure
+ * surface is what PRs 5/6/7 will call).
+ */
+
+// ──────────────────────────────────────────────────────────────────────────
+// Public types
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * A memory candidate as fed into review-context ranking. The shape is a
+ * deliberate subset of the core `MemorySummary` / recall result — only the
+ * fields we actually need — so this module stays decoupled from the rest of
+ * the codebase and can be reused by CLI tools, bench fixtures, etc.
+ */
+export interface ReviewCandidate {
+  /** Opaque identifier. Echoed unchanged in the output. */
+  id: string;
+  /**
+   * Pre-review relevance score from the upstream recall pipeline. Higher is
+   * better. `0` is treated as "no prior signal" and gets the full review
+   * boost when a path match is found.
+   */
+  score: number;
+  /**
+   * References the memory mentions (file paths, entity names, etc.). Used
+   * to decide whether any touched file appears in the memory's scope.
+   *
+   * Accepts `undefined`/missing so callers can pass sparse records from
+   * legacy storage without pre-filling.
+   */
+  entityRefs?: string[];
+}
+
+export interface ReviewContext {
+  /**
+   * Normalized file paths touched by the diff. Each entry is forward-slashed
+   * and relative to the repo root when possible.
+   */
+  touchedFiles: string[];
+  /**
+   * Candidates re-sorted so memories whose `entityRefs` mention a touched
+   * path are boosted. Shape matches the input `ReviewCandidate[]` — the
+   * boost is recorded on each entry as `boost` for observability.
+   */
+  rankedRecall: Array<ReviewCandidate & { boost: number }>;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Review-prompt heuristic
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Keyword list from the #569 design doc, plus obvious paraphrases. All
+ * matching is case-insensitive and whole-word (so `reviewer` doesn't trigger
+ * on `review` alone).
+ */
+const REVIEW_KEYWORD_PATTERNS: RegExp[] = [
+  /\breview\b/i,
+  /\bdiff\b/i,
+  /\bwhat changed\b/i,
+  /\blook at this pr\b/i,
+  /\bwhat('?s|\s+is)\s+in\s+this\s+(pr|patch|diff|change)\b/i,
+  /\bcode review\b/i,
+];
+
+/**
+ * `true` when the prompt looks like a review / diff-explanation request.
+ *
+ * Empty / non-string input → `false` (the caller shouldn't branch on an
+ * invalid prompt).
+ */
+export function isReviewPrompt(prompt: string | null | undefined): boolean {
+  if (typeof prompt !== "string") return false;
+  const trimmed = prompt.trim();
+  if (!trimmed) return false;
+  return REVIEW_KEYWORD_PATTERNS.some((re) => re.test(trimmed));
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Unified-diff parser — extract touched files
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a unified diff and return the set of files touched. Accepts both the
+ * `diff --git` form (`diff --git a/foo b/bar`) and the `--- / +++` form
+ * (`--- a/foo\n+++ b/bar`). Returns deduplicated, repo-root-relative paths
+ * (with the conventional `a/` / `b/` prefixes stripped).
+ *
+ * Path entries of `/dev/null` (used in adds/deletes) are excluded.
+ */
+export function parseTouchedFiles(diff: string | null | undefined): string[] {
+  if (typeof diff !== "string" || !diff.trim()) return [];
+  const touched = new Set<string>();
+  const lines = diff.split(/\r?\n/);
+
+  for (const line of lines) {
+    // `diff --git a/foo/bar.ts b/foo/bar.ts`
+    //
+    // Paths may be quoted by git when they contain spaces or non-ASCII
+    // characters, e.g. `diff --git "a/src/my file.ts" "b/src/my file.ts"`.
+    // The two paths are always separated by whitespace at the top level, but
+    // whitespace INSIDE quoted paths must NOT split the tokens. Parse the
+    // two paths with an explicit tokenizer instead of a `\S+`-based regex
+    // (which would shatter `"a/my file.ts"` into `"a/my` / `file.ts"`).
+    const gitPrefix = line.match(/^diff --git\s+/);
+    if (gitPrefix) {
+      const rest = line.slice(gitPrefix[0].length);
+      const paths = splitDiffGitPaths(rest);
+      if (paths) {
+        for (const raw of paths) {
+          const stripped = stripDiffPathPrefix(raw);
+          if (stripped && stripped !== "/dev/null") touched.add(stripped);
+        }
+      }
+      continue;
+    }
+    // `--- a/foo/bar.ts` or `+++ b/foo/bar.ts` — or quoted:
+    // `--- "a/foo bar.ts"` / `+++ "b/foo bar.ts"` when git emits C-quoted
+    // paths for whitespace or non-ASCII filenames.
+    //
+    // Matched with an anchored prefix and an explicit tokenizer for the
+    // tail so quoted paths containing whitespace are not split on the
+    // first internal space. The previous `\S+` form silently dropped
+    // everything after the first whitespace in a quoted path.
+    const headerPrefix = line.match(/^(?:---|\+\+\+)[ \t]+/);
+    if (headerPrefix) {
+      const tail = line.slice(headerPrefix[0].length).replace(/[ \t]+$/, "");
+      const raw = extractSingleDiffPathToken(tail);
+      if (raw) {
+        const stripped = stripDiffPathPrefix(raw);
+        if (stripped && stripped !== "/dev/null") touched.add(stripped);
+      }
+    }
+  }
+
+  return Array.from(touched).sort();
+}
+
+/**
+ * Extract the single path token from the tail of a `---` / `+++` header
+ * line. Returns `null` when the tail is empty or malformed (e.g. an
+ * unterminated quoted path). The whole tail is consumed — trailing
+ * timestamps from non-git diff frontends (`--- a/foo	2023-01-01`) fall
+ * into a leading-token extraction like the quoted-form case.
+ */
+function extractSingleDiffPathToken(tail: string): string | null {
+  if (tail.length === 0) return null;
+  if (tail[0] === '"') {
+    let j = 1;
+    while (j < tail.length) {
+      if (tail[j] === "\\" && j + 1 < tail.length) {
+        j += 2;
+        continue;
+      }
+      if (tail[j] === '"') break;
+      j += 1;
+    }
+    if (j >= tail.length) return null; // unterminated quoted path
+    return tail.slice(0, j + 1);
+  }
+  // Unquoted: consume up to the first tab or whitespace-run, so standard
+  // `--- a/foo	<timestamp>` lines surface just `a/foo`. For ordinary
+  // git-style output the tail has no whitespace at all.
+  let j = 0;
+  while (j < tail.length && tail[j] !== " " && tail[j] !== "\t") j += 1;
+  return tail.slice(0, j);
+}
+
+/**
+ * Split the `a-path b-path` portion of a `diff --git` line into exactly two
+ * path tokens, respecting git's quoting convention. Returns `null` when the
+ * input cannot be parsed into exactly two tokens.
+ */
+function splitDiffGitPaths(rest: string): [string, string] | null {
+  const tokens: string[] = [];
+  let i = 0;
+  while (i < rest.length && tokens.length < 2) {
+    // Skip leading whitespace between tokens.
+    while (i < rest.length && (rest[i] === " " || rest[i] === "\t")) i += 1;
+    if (i >= rest.length) break;
+    if (rest[i] === '"') {
+      // Quoted path: consume up to the matching unescaped `"`. Git escapes
+      // inner quotes as `\"`, so we respect backslash escaping.
+      let j = i + 1;
+      while (j < rest.length) {
+        if (rest[j] === "\\" && j + 1 < rest.length) {
+          j += 2;
+          continue;
+        }
+        if (rest[j] === '"') break;
+        j += 1;
+      }
+      if (j >= rest.length) return null; // unterminated quoted path
+      tokens.push(rest.slice(i, j + 1));
+      i = j + 1;
+    } else {
+      // Unquoted path: run of non-whitespace.
+      let j = i;
+      while (j < rest.length && rest[j] !== " " && rest[j] !== "\t") j += 1;
+      tokens.push(rest.slice(i, j));
+      i = j;
+    }
+  }
+  if (tokens.length !== 2) return null;
+  return [tokens[0]!, tokens[1]!];
+}
+
+function stripDiffPathPrefix(raw: string): string {
+  // Git conventionally prefixes paths with `a/` or `b/` in diffs, and
+  // quotes the whole path (including the prefix) when it contains spaces or
+  // non-ASCII bytes. Quote-stripping must therefore happen BEFORE the
+  // prefix check — otherwise `"a/path with spaces.ts"` still starts with
+  // `"a` and the prefix is never recognized.
+  let s = raw;
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    s = s.slice(1, -1);
+    // Git octal-escapes non-ASCII and escapes inner backslashes/quotes via
+    // the C-quoted path form. We handle the common cases (`\"`, `\\`) so
+    // the rest of the pipeline gets the raw filename. Octal escapes for
+    // non-ASCII are left as-is here — they are extremely rare and the
+    // touched-file set is only used for lexical matches against
+    // entityRefs, where matching either form produces the same hit.
+    s = s.replace(/\\(["\\])/g, "$1");
+  }
+  // Normalize Windows-style backslashes. Must happen AFTER quote stripping
+  // so that the `\"` and `\\` escape pairs above aren't corrupted.
+  s = s.replace(/\\/g, "/");
+  if (s.startsWith("a/") || s.startsWith("b/")) s = s.slice(2);
+  return s;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Ranking
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Additive boost per matching touched-file. Tuned so that a single exact
+ * match is enough to float a `score=0` candidate above a `score=0.4`
+ * unmatched peer, but not so large it buries multi-signal results. `0.5`
+ * per match, capped at `1.0` so three matches don't eclipse strong recall.
+ */
+const BOOST_PER_MATCH = 0.5;
+const MAX_BOOST = 1.0;
+
+/**
+ * Count how many touched files appear in a memory's entityRefs. Matches are
+ * literal substring matches on either direction — either the ref contains
+ * the path, or the path contains the ref — so both
+ *   - `"src/foo.ts"` refs matching a touched `"src/foo.ts"`, and
+ *   - `"foo.ts"` refs matching a touched `"src/foo.ts"`
+ * succeed.
+ */
+function countPathHits(entityRefs: string[] | undefined, touchedFiles: string[]): number {
+  if (!entityRefs || entityRefs.length === 0) return 0;
+  if (touchedFiles.length === 0) return 0;
+  let hits = 0;
+  for (const ref of entityRefs) {
+    if (typeof ref !== "string" || !ref) continue;
+    const lowered = ref.toLowerCase();
+    for (const file of touchedFiles) {
+      const flower = file.toLowerCase();
+      if (lowered === flower) {
+        hits += 1;
+        break;
+      }
+      if (lowered.includes(flower) || flower.includes(lowered)) {
+        hits += 1;
+        break;
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Build a review-context ranking for a set of candidate memories.
+ *
+ * Contract:
+ *   - `touchedFiles` is the parsed diff file list.
+ *   - `candidates` is passed through unchanged when no boost applies.
+ *   - When a boost applies, the result is sorted by `(score + boost)` desc,
+ *     with a stable secondary sort on the original `id` for determinism
+ *     (CLAUDE.md #19 — comparators must return 0 for equal items).
+ */
+export function rankReviewCandidates(
+  candidates: ReviewCandidate[],
+  touchedFiles: string[],
+): Array<ReviewCandidate & { boost: number }> {
+  const annotated: Array<ReviewCandidate & { boost: number }> = candidates.map((c) => {
+    const hits = countPathHits(c.entityRefs, touchedFiles);
+    const boost = Math.min(MAX_BOOST, hits * BOOST_PER_MATCH);
+    return { ...c, boost };
+  });
+
+  annotated.sort((a, b) => {
+    const adjA = a.score + a.boost;
+    const adjB = b.score + b.boost;
+    if (adjA !== adjB) return adjB - adjA;
+    // Stable secondary sort for deterministic ordering on ties.
+    if (a.id < b.id) return -1;
+    if (a.id > b.id) return 1;
+    return 0;
+  });
+
+  return annotated;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Packer entry point
+// ──────────────────────────────────────────────────────────────────────────
+
+export interface PackReviewContextInput {
+  /** Unified diff, as produced by `git diff`. */
+  diff: string | null | undefined;
+  /** Candidate memories from the upstream recall pipeline. */
+  candidates: ReviewCandidate[];
+}
+
+/**
+ * Top-level entry point used by the orchestrator (and CLI / bench) when a
+ * review-intent prompt is detected.
+ *
+ * Parses the diff, re-ranks the candidates, and returns both artefacts so
+ * the caller can surface `touchedFiles` as context and `rankedRecall` as
+ * the recall result.
+ */
+export function packReviewContext(input: PackReviewContextInput): ReviewContext {
+  const touchedFiles = parseTouchedFiles(input.diff);
+  const rankedRecall = rankReviewCandidates(input.candidates, touchedFiles);
+  return { touchedFiles, rankedRecall };
+}