@mrclrchtr/supi-review 1.6.0 → 1.8.0

package/README.md

@@ -8,7 +8,7 @@ Adds an interactive `/supi-review` command to the [pi coding agent](https://gith
 pi install npm:@mrclrchtr/supi-review
 ```
 
-This is a **beta** package. It is not bundled in `@mrclrchtr/supi`.
+This is a **beta** package. Install individually.
 
 For local development:
 
@@ -27,7 +27,7 @@ After install, pi gets one command:
 The reviewer runs in managed child agent sessions:
 
 - a **brief synthesizer** creates a structured review brief from the active session branch
-- a **read-only reviewer** inspects the selected snapshot and submits structured findings
+- a **read-only reviewer** inspects the selected snapshot (without receiving bulk inline diffs) and submits structured findings
 
 ## Review flow
 
@@ -38,8 +38,8 @@ The reviewer runs in managed child agent sessions:
 3. optionally add a short note
 4. resolve the snapshot
 5. synthesize a review brief from the current session history
-6. preview the synthesized brief + prompt coverage
-7. run the review with a live progress widget
+6. preview the synthesized brief + compact prompt preview
+7. the reviewer fetches per-file diffs on demand via snapshot-aware tools; live progress widget shows activity
 8. show the structured result as a custom message
 9. if findings exist, hand off to the main agent so it can ask what to do next
 
@@ -58,7 +58,8 @@ The generated review prompt is **not** just a static diff wrapper.
 Before the actual review starts, the package:
 
 - resolves the **active session branch into the current LLM-visible context**
-- extracts high-signal user/assistant/custom/compaction context from that resolved view
+- **serializes** that resolved context into a compaction-style transcript
+- feeds the serialized transcript (plus snapshot + optional note) to a dedicated brief synthesizer
 - synthesizes a structured brief with:
   - summary
   - intended outcome
@@ -69,7 +70,9 @@ Before the actual review starts, the package:
 
 The synthesizer also receives a bounded diff excerpt from the snapshot so it can reason about actual code changes, not just filenames.
 
-That synthesized brief is then combined with the git snapshot into the final reviewer prompt.
+That synthesized brief is then combined with the git snapshot into a compact reviewer prompt. The prompt contains the brief, file manifest, and per-file overview, but no large inline diffs. Instead, the reviewer session gets snapshot-aware tools (`read_snapshot_diff`, `read_snapshot_file`) to fetch exact per-file diffs and before/after file contents on demand.
+
+The session-transcript approach mirrors how Pi summarizes context for compaction: the entire resolved conversation is rendered in a readable label format and sent to the model as a whole, rather than relying on heuristic excerpt ranking.
 
 ## Model selection
 
@@ -104,9 +107,10 @@ When a successful review contains findings, `supi-review` also injects an agent-
 - `src/review.ts` — command orchestration and interactive flow
 - `src/model.ts` — explicit model selection helpers
 - `src/git.ts` — git snapshot resolution
-- `src/history/collect.ts` — active-branch evidence extraction
+- `src/history/collect.ts` — compaction-style session-context serialization
 - `src/history/synthesize.ts` — brief synthesis orchestration
 - `src/target/packet.ts` — final reviewer packet builder
 - `src/tool/brief-runner.ts` — brief synthesis child session
-- `src/tool/review-runner.ts` — read-only reviewer child session
+- `src/tool/review-runner.ts` — read-only reviewer child session with snapshot-aware tools
+- `src/tool/snapshot-tools.ts` — per-file diff and before/after content tools scoped to the selected snapshot
 - `src/ui/renderer.ts` — structured result rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "SuPi Review extension — structured code review via /supi-review command",
   "license": "MIT",
   "repository": {

package/src/git.ts

@@ -1,10 +1,11 @@
+// biome-ignore lint/nursery/noExcessiveLinesPerFile: many tightly-coupled git helpers; splitting would create cross-ref overhead
 import { execFile } from "node:child_process";
-import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
 import { promisify } from "node:util";
-import type { DiffStats, ReviewSnapshot } from "./types.ts";
+import type { DiffStats, ReviewSnapshot, ReviewTargetSpec } from "./types.ts";
 
 const execFileAsync = promisify(execFile);
-
 const GIT_TIMEOUT_MS = 30_000;
 
 function scrubGitEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -237,11 +238,7 @@ export async function resolveWorkingTreeSnapshot(
     getUncommittedDiff(repoPath),
     getUncommittedFileNames(repoPath),
   ]);
-
-  if (!diffText.trim() && changedFiles.length === 0) {
-    return undefined;
-  }
-
+  if (!diffText.trim() && changedFiles.length === 0) return undefined;
   return {
     target: { kind: "working-tree" },
     title: "Working tree changes",
@@ -257,19 +254,12 @@ export async function resolveBranchSnapshot(
   base: string,
 ): Promise<ReviewSnapshot | undefined> {
   const baseSha = await getMergeBase(repoPath, base);
-  if (!baseSha) {
-    return undefined;
-  }
-
+  if (!baseSha) return undefined;
   const [diffText, changedFiles] = await Promise.all([
     getDiff(repoPath, baseSha),
     getDiffFileNames(repoPath, baseSha),
   ]);
-
-  if (!diffText.trim() && changedFiles.length === 0) {
-    return undefined;
-  }
-
+  if (!diffText.trim() && changedFiles.length === 0) return undefined;
   return {
     target: { kind: "branch", base },
     title: `Changes vs ${base}`,
@@ -288,11 +278,7 @@ export async function resolveCommitSnapshot(
     getCommitShow(repoPath, sha),
     getCommitFileNames(repoPath, sha),
   ]);
-
-  if (!diffText.trim() && changedFiles.length === 0) {
-    return undefined;
-  }
-
+  if (!diffText.trim() && changedFiles.length === 0) return undefined;
   return {
     target: { kind: "commit", sha },
     title: `Commit ${sha.slice(0, 7)}`,
@@ -302,6 +288,122 @@ export async function resolveCommitSnapshot(
   };
 }
 
+/** Get the per-file diff for a single changed file in the snapshot. */
+export async function getSnapshotFileDiff(
+  repoPath: string,
+  snapshot: ReviewSnapshot,
+  file: string,
+): Promise<string> {
+  const { target } = snapshot;
+  switch (target.kind) {
+    case "working-tree": {
+      const { stdout } = await execFileAsync(
+        "git",
+        ["diff", "HEAD", "--", file],
+        gitExecOptions(repoPath),
+      );
+      return stdout;
+    }
+    case "branch": {
+      const baseSha = await getMergeBase(repoPath, target.base);
+      if (!baseSha) return "";
+      const { stdout } = await execFileAsync(
+        "git",
+        ["diff", baseSha, "HEAD", "--", file],
+        gitExecOptions(repoPath),
+      );
+      return stdout;
+    }
+    case "commit": {
+      const { stdout } = await execFileAsync(
+        "git",
+        ["show", target.sha, "--", file],
+        gitExecOptions(repoPath),
+      );
+      return stdout;
+    }
+  }
+}
+
+/** Run `git show <ref>:<file>` and return the blob content. */
+async function showGitBlob(repoPath: string, ref: string, file: string): Promise<string> {
+  const { stdout } = await execFileAsync(
+    "git",
+    ["show", `${ref}:${file}`],
+    gitExecOptions(repoPath),
+  );
+  return stdout;
+}
+
+async function resolveWorkingTreeContent(
+  repoPath: string,
+  file: string,
+  side: "before" | "after",
+): Promise<string | undefined> {
+  if (side === "before") {
+    try {
+      return await showGitBlob(repoPath, "HEAD", file);
+    } catch {
+      return undefined;
+    }
+  }
+  try {
+    return await readFile(join(repoPath, file), "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+async function resolveBranchContent(
+  repoPath: string,
+  target: ReviewTargetSpec & { kind: "branch" },
+  file: string,
+  side: "before" | "after",
+): Promise<string | undefined> {
+  const baseSha = await getMergeBase(repoPath, target.base);
+  if (!baseSha) return undefined;
+  const ref = side === "before" ? baseSha : "HEAD";
+  try {
+    return await showGitBlob(repoPath, ref, file);
+  } catch (err) {
+    if (side === "before") return undefined;
+    throw err;
+  }
+}
+
+async function resolveCommitContent(
+  repoPath: string,
+  target: ReviewTargetSpec & { kind: "commit" },
+  file: string,
+  side: "before" | "after",
+): Promise<string | undefined> {
+  const ref = side === "before" ? `${target.sha}^` : target.sha;
+  try {
+    return await showGitBlob(repoPath, ref, file);
+  } catch (err) {
+    if (side === "before") return undefined;
+    throw err;
+  }
+}
+
+/** Get before or after content for a single changed file in the snapshot. Returns undefined when legitimately unavailable; propagates unexpected errors. */
+export async function getSnapshotFileContent(
+  repoPath: string,
+  snapshot: ReviewSnapshot,
+  file: string,
+  side: "before" | "after",
+): Promise<string | undefined> {
+  const { target } = snapshot;
+  switch (target.kind) {
+    case "working-tree":
+      return resolveWorkingTreeContent(repoPath, file, side);
+    case "branch":
+      return resolveBranchContent(repoPath, target, file, side);
+    case "commit":
+      return resolveCommitContent(repoPath, target, file, side);
+  }
+}
+
 /** Convenience label for one changed file, used in synthesized prompts/UI. */
 export function formatChangedFileLabel(file: string): string {
   return basename(file) === file ? file : `${basename(file)} (${file})`;

package/src/history/collect.ts

@@ -1,114 +1,134 @@
 import type { SessionContext } from "@earendil-works/pi-coding-agent";
-import type { HistoryEvidence, ReviewSnapshot } from "../types.ts";
-
-const INTENT_PATTERN =
-  /\b(fix|refactor|rename|preserve|avoid|should|must|ensure|intended|goal|risk|concern|regression|security|correctness|performance|api|breaking|review)\b/i;
 
 type ResolvedSessionMessage = SessionContext["messages"][number];
 
+const DEFAULT_MAX_CHARS = 8_000;
+
+export interface SerializeSessionContextOptions {
+  maxChars?: number;
+}
+
 /**
- * Extract the highest-signal evidence from the resolved LLM-visible session context.
+ * Serialize the resolved LLM-visible session context into a compaction-style
+ * readable transcript for the brief synthesizer.
  *
- * The collector intentionally favors user intent, assistant plans, compaction
- * summaries, and custom extension messages over raw tool chatter.
+ * This mirrors the overall approach Pi uses for compaction:
+ * - messages are labeled by role and rendered in chronological order
+ * - compaction and branch summaries appear with their own labels
+ * - the output is bounded so the synthesizer stays predictable on long sessions
+ * - no heuristic ranking or scoring is applied
  */
-export function collectHistoryEvidence(
+export function serializeSessionContext(
   messages: ResolvedSessionMessage[],
-  snapshot: ReviewSnapshot,
-  note?: string,
-): HistoryEvidence[] {
-  const scoringContext = {
-    changedPathTokens: collectPathTokens(snapshot.changedFiles),
-    noteTokens: collectFreeformTokens(note),
-    total: messages.length,
-  };
-
-  const scored = messages
-    .map((message) => toEvidence(message))
+  options?: SerializeSessionContextOptions,
+): string {
+  const maxChars = options?.maxChars ?? DEFAULT_MAX_CHARS;
+  if (messages.length === 0) return "";
+
+  const entries = messages
+    .map((message) => serializeEntry(message))
     .filter(
-      (evidence): evidence is Omit<HistoryEvidence, "score" | "reason"> => evidence !== undefined,
-    )
-    .map((evidence, index) => scoreEvidence(evidence, index, scoringContext))
-    .sort((a, b) => b.score - a.score || b.text.length - a.text.length);
+      (entry): entry is { label: string; text: string; isSummary: boolean } => entry !== undefined,
+    );
+
+  if (entries.length === 0) return "";
+
+  // Separate summary entries (compaction/branch summaries) from regular entries
+  const summaryEntries = entries.filter((e) => e.isSummary);
+  const regularEntries = entries.filter((e) => !e.isSummary);
+
+  // Estimate the total size if we keep everything
+  const allLines = entries.map(formatEntry);
+  const totalSize = measureLines(allLines);
+
+  if (totalSize <= maxChars) {
+    return allLines.join("\n");
+  }
+
+  // Build the output: always include summaries, then as many recent regular entries as fit
+  const summaryLines = summaryEntries.map(formatEntry);
+
+  // Walk regular entries from newest to oldest, keeping as many as fit
+  const keptRegular: typeof regularEntries = [];
+  let size = measureLines(summaryLines);
+
+  for (let i = regularEntries.length - 1; i >= 0; i--) {
+    const line = formatEntry(regularEntries[i]);
+    const lineLen = line.length + 1; // +1 for newline
+    if (keptRegular.length > 0 && size + lineLen > maxChars) {
+      break;
+    }
+    keptRegular.unshift(regularEntries[i]);
+    size += lineLen;
+  }
+
+  // Build final output: summaries first, then kept recent entries
+  const keptLines = [...summaryLines, ...keptRegular.map(formatEntry)];
 
-  return capEvidence(scored, 10, 4_500);
+  // If still nothing fits with summaries alone, truncate the summaries
+  if (keptLines.length > 0) {
+    const output = keptLines.join("\n");
+    if (output.length <= maxChars) return output;
+  }
+
+  // Last resort: truncate the full output
+  return keepFirstLines(keptLines, maxChars);
+}
+
+function formatEntry(entry: { label: string; text: string }): string {
+  return `[${entry.label}]\n${entry.text}`;
 }
 
-function toEvidence(
+function measureLines(lines: string[]): number {
+  return lines.reduce((acc, line) => acc + line.length + 1, 0); // +1 for newline
+}
+
+function keepFirstLines(lines: string[], maxChars: number): string {
+  const kept: string[] = [];
+  let size = 0;
+  for (const line of lines) {
+    const lineLen = line.length + 1;
+    if (size + lineLen > maxChars) break;
+    kept.push(line);
+    size += lineLen;
+  }
+  return kept.join("\n");
+}
+
+function serializeEntry(
   message: ResolvedSessionMessage,
-): Omit<HistoryEvidence, "score" | "reason"> | undefined {
+): { label: string; text: string; isSummary: boolean } | undefined {
   switch (message.role) {
     case "user":
     case "assistant": {
+      const text = normalizeText(extractMessageText(message.content));
+      if (!text) return undefined;
       return {
-        kind: message.role,
-        text: normalizeText(extractMessageText(message.content)),
+        label: message.role === "user" ? "User" : "Assistant",
+        text,
+        isSummary: false,
       };
     }
     case "custom": {
-      return {
-        kind: "custom",
-        text: normalizeText(extractMessageText(message.content)),
-      };
+      const text = normalizeText(extractMessageText(message.content));
+      if (!text) return undefined;
+      return { label: "Custom", text, isSummary: false };
     }
     case "compactionSummary": {
-      return {
-        kind: "compaction",
-        text: normalizeText(message.summary),
-      };
+      const text = normalizeText(message.summary);
+      if (!text) return undefined;
+      return { label: "Compaction summary", text, isSummary: true };
     }
     case "branchSummary": {
-      return {
-        kind: "branch-summary",
-        text: normalizeText(message.summary),
-      };
+      const text = normalizeText(message.summary);
+      if (!text) return undefined;
+      return { label: "Branch summary", text, isSummary: true };
     }
     default:
       return undefined;
   }
 }
 
-function scoreEvidence(
-  evidence: Omit<HistoryEvidence, "score" | "reason">,
-  index: number,
-  context: { total: number; changedPathTokens: string[]; noteTokens: string[] },
-): HistoryEvidence {
-  const recencyBoost = context.total > 0 ? (index / context.total) * 3 : 0;
-  const pathMatches = countTokenMatches(evidence.text, context.changedPathTokens);
-  const noteMatches = countTokenMatches(evidence.text, context.noteTokens);
-  const intentBoost = INTENT_PATTERN.test(evidence.text) ? 4 : 0;
-  const shortTextPenalty = evidence.text.length < 24 ? -2 : 0;
-  const longTextPenalty = evidence.text.length > 900 ? -1 : 0;
-  const score =
-    baseKindScore(evidence.kind) +
-    recencyBoost +
-    pathMatches * 3 +
-    noteMatches * 2 +
-    intentBoost +
-    shortTextPenalty +
-    longTextPenalty;
-
-  return {
-    ...evidence,
-    score,
-    reason: buildReason(pathMatches, noteMatches, intentBoost),
-  };
-}
-
-function buildReason(pathMatches: number, noteMatches: number, intentBoost: number): string {
-  const reasons: string[] = [];
-  if (pathMatches > 0) {
-    reasons.push(`mentions ${pathMatches} changed-path token${pathMatches === 1 ? "" : "s"}`);
-  }
-  if (noteMatches > 0) {
-    reasons.push(`matches ${noteMatches} note token${noteMatches === 1 ? "" : "s"}`);
-  }
-  if (intentBoost > 0) {
-    reasons.push("contains intent/constraint language");
-  }
-  return reasons.join(", ") || "high-signal session context";
-}
-
 function extractMessageText(content: unknown): string {
   if (typeof content === "string") {
     return content;
@@ -131,80 +151,3 @@ function extractMessageText(content: unknown): string {
 function normalizeText(text: string): string {
   return text.replace(/\s+/g, " ").trim();
 }
-
-function collectPathTokens(paths: string[]): string[] {
-  const tokens = new Set<string>();
-
-  for (const path of paths) {
-    for (const part of path.split(/[\\/]/)) {
-      addToken(tokens, part);
-      for (const inner of part.split(/[-_.]/)) {
-        addToken(tokens, inner);
-      }
-    }
-    addToken(tokens, path);
-  }
-
-  return Array.from(tokens);
-}
-
-function collectFreeformTokens(text: string | undefined): string[] {
-  if (!text) return [];
-
-  const tokens = new Set<string>();
-  for (const part of text.split(/\W+/)) {
-    addToken(tokens, part);
-  }
-  return Array.from(tokens);
-}
-
-function addToken(tokens: Set<string>, token: string): void {
-  const normalized = token.trim().toLowerCase();
-  if (normalized.length < 3) return;
-  tokens.add(normalized);
-}
-
-function countTokenMatches(text: string, tokens: string[]): number {
-  if (tokens.length === 0 || text.length === 0) return 0;
-  const lower = text.toLowerCase();
-  return tokens.reduce((count, token) => count + (lower.includes(token) ? 1 : 0), 0);
-}
-
-function baseKindScore(kind: HistoryEvidence["kind"]): number {
-  switch (kind) {
-    case "user":
-      return 8;
-    case "assistant":
-      return 5;
-    case "compaction":
-    case "branch-summary":
-      return 6;
-    case "custom":
-      return 4;
-  }
-}
-
-function capEvidence(
-  evidence: HistoryEvidence[],
-  maxItems: number,
-  maxChars: number,
-): HistoryEvidence[] {
-  const kept: HistoryEvidence[] = [];
-  let used = 0;
-
-  for (const item of evidence) {
-    if (kept.length >= maxItems) break;
-    const text = truncate(item.text, 600);
-    const nextUsed = used + text.length;
-    if (kept.length > 0 && nextUsed > maxChars) break;
-    kept.push({ ...item, text });
-    used = nextUsed;
-  }
-
-  return kept;
-}
-
-function truncate(text: string, maxChars: number): string {
-  if (text.length <= maxChars) return text;
-  return `${text.slice(0, maxChars)}…`;
-}

package/src/history/synthesize.ts

@@ -1,7 +1,7 @@
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { runBriefSynthesis } from "../tool/brief-runner.ts";
 import type { BriefSynthesisRunResult, ReviewProgress } from "../tool/runner-types.ts";
-import type { HistoryEvidence, ReviewModelSelection, ReviewSnapshot } from "../types.ts";
+import type { ReviewModelSelection, ReviewSnapshot } from "../types.ts";
 
 const DIFF_EXCERPT_CHAR_BUDGET = 12_000;
 
@@ -10,20 +10,21 @@ export interface SynthesizeReviewBriefOptions {
   modelRegistry: ModelRegistry;
   cwd: string;
   snapshot: ReviewSnapshot;
-  evidence: HistoryEvidence[];
+  serializedContext: string;
   note?: string;
   signal?: AbortSignal;
   onProgress?: (progress: ReviewProgress) => void;
 }
 
-/** Synthesize a structured review brief from the current snapshot and session evidence. */
+/** Synthesize a structured review brief from the current snapshot and session context. */
 export function synthesizeReviewBrief(
   options: SynthesizeReviewBriefOptions,
 ): Promise<BriefSynthesisRunResult> {
-  const { model, modelRegistry, cwd, snapshot, evidence, note, signal, onProgress } = options;
+  const { model, modelRegistry, cwd, snapshot, serializedContext, note, signal, onProgress } =
+    options;
 
   return runBriefSynthesis({
-    prompt: buildBriefSynthesisPrompt(snapshot, evidence, note),
+    prompt: buildBriefSynthesisPrompt(snapshot, serializedContext, note),
     model: model.model,
     modelRegistry,
     cwd,
@@ -34,7 +35,7 @@ export function synthesizeReviewBrief(
 
 export function buildBriefSynthesisPrompt(
   snapshot: ReviewSnapshot,
-  evidence: HistoryEvidence[],
+  serializedContext: string,
   note?: string,
 ): string {
   const diffExcerpt = buildDiffExcerpt(snapshot.diffText);
@@ -65,18 +66,11 @@ export function buildBriefSynthesisPrompt(
     parts.push("", "## User note", note.trim());
   }
 
-  parts.push("", "## Session evidence");
-  if (evidence.length === 0) {
-    parts.push(
-      "- No strong session evidence was extracted. Derive a minimal brief from the snapshot only.",
-    );
+  parts.push("", "## Serialized session context");
+  if (serializedContext.trim()) {
+    parts.push(serializedContext.trim());
   } else {
-    parts.push(
-      ...evidence.flatMap((item, index) => [
-        `${index + 1}. [${item.kind}] ${item.reason}`,
-        `   ${item.text}`,
-      ]),
-    );
+    parts.push("No session context was available. Derive the brief from the snapshot only.");
   }
 
   parts.push(
@@ -87,7 +81,9 @@ export function buildBriefSynthesisPrompt(
     "- intendedOutcome: what the session seems to be trying to achieve",
     "- constraints: invariants or requirements to preserve",
     "- focusAreas: what the reviewer should inspect carefully",
-    "- riskyFiles: changed files that seem especially important or risky",
+    "- riskyFiles: changed files that seem especially important or risky.",
+    "  Prioritize files touching auth, data handling, core logic, error handling, or public APIs.",
+    "  Include only files from the changed-files list above.",
     "- unresolvedQuestions: ambiguities or concerns that remain unclear",
   );