pi-diff-review 0.1.5 → 0.1.7

package/README.md

@@ -2,9 +2,9 @@
 
 # pi-diff-review
 
-Easily provide code reviews directly within [pi](https://pi.dev/).
+Embedded code reviews directly directly within [pi](https://pi.dev/).
 
-<img width="1095" height="853" alt="pi-diff-review-screenshot" src="https://github.com/user-attachments/assets/f1a39117-f2a6-4ee7-bf72-a299990ab1dd" />
+<img width="1986" height="1556" alt="pi-diff-review-screenshot(1)" src="https://github.com/user-attachments/assets/3fd00163-5d19-489b-94ed-3d4816c6cad3" />
 
 ## Install
 
@@ -14,8 +14,6 @@ Install from npm:
 pi install npm:pi-diff-review
 ```
 
-Package: https://www.npmjs.com/package/pi-diff-review
-
 Or install directly from GitHub:
 
 ```bash
@@ -30,6 +28,7 @@ pi install https://github.com/cmpadden/pi-diff-review
 - `g/G` to jump to the top or bottom of the diff
 - `ctrl-u` / `ctrl-d` to move up/down by half a page
 - `t` toggles the diff between unified and side-by-side split rendering
+- `?` toggles an AI-generated explanation for the current hunk
 - `J/K` to extend a highlighted selection into a comment range
 - `esc` clears the active selection, or exits review when no selection is active
 - `n/p` to jump hunks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-diff-review",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local diff review TUI extension for pi",
   "license": "MIT",
   "repository": {
@@ -49,6 +49,7 @@
     ]
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
     "@pierre/diffs": "^1.1.21"
   }
 }

package/src/explain.ts

@@ -0,0 +1,106 @@
+import { streamSimple } from "@earendil-works/pi-ai";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage, Context } from "@earendil-works/pi-ai";
+
+export type ExplanationScope = {
+  key: string;
+  kind: "hunk";
+  title: string;
+  filePath?: string;
+  diffText: string;
+};
+
+export type ExplanationState =
+  | { status: "loading"; text: string }
+  | { status: "ready"; text: string }
+  | { status: "error"; message: string };
+
+export type DiffExplainer = {
+  explain(
+    scope: ExplanationScope,
+    options?: {
+      signal?: AbortSignal;
+      onDelta?: (delta: string) => void;
+    },
+  ): Promise<string>;
+};
+
+export function buildExplanationPrompt(scope: ExplanationScope): string {
+  return `Explain this git diff hunk for a code reviewer.
+
+Focus on:
+- what changed
+- why it matters
+- behavioral, API, or test implications
+- notable risks or edge cases
+
+Keep it concise and practical. Do not suggest code changes unless they are directly relevant to understanding the diff.
+
+\`\`\`diff
+${scope.diffText}
+\`\`\``;
+}
+
+export class PiModelDiffExplainer implements DiffExplainer {
+  constructor(private ctx: ExtensionCommandContext) {}
+
+  async explain(
+    scope: ExplanationScope,
+    options: {
+      signal?: AbortSignal;
+      onDelta?: (delta: string) => void;
+    } = {},
+  ): Promise<string> {
+    const model = this.ctx.model;
+    if (!model) {
+      throw new Error("No model is selected.");
+    }
+
+    const auth = await this.ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      throw new Error(auth.error);
+    }
+
+    const context: Context = {
+      systemPrompt:
+        "You explain code diffs clearly and concisely for code review. Focus on intent, behavior, and risk. Avoid restating every changed line.",
+      messages: [
+        {
+          role: "user",
+          content: buildExplanationPrompt(scope),
+          timestamp: Date.now(),
+        },
+      ],
+    };
+
+    let streamedText = "";
+    const stream = streamSimple(model, context, {
+      apiKey: auth.apiKey,
+      headers: auth.headers,
+      signal: options.signal,
+      maxTokens: 800,
+      reasoning: "minimal",
+    });
+
+    for await (const event of stream) {
+      if (event.type === "text_delta") {
+        streamedText += event.delta;
+        options.onDelta?.(event.delta);
+      } else if (event.type === "done") {
+        return extractText(event.message) || streamedText.trim();
+      } else if (event.type === "error") {
+        throw new Error(event.error.errorMessage ?? "Explanation failed.");
+      }
+    }
+
+    return streamedText.trim();
+  }
+}
+
+function extractText(message: AssistantMessage): string {
+  return message.content
+    .filter((content) => content.type === "text")
+    .map((content) => content.text)
+    .join("")
+    .trim();
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { getDiff, parseDiffSource } from "./diff-source.ts";
 import { parseDiff } from "./diff-parser.ts";
+import { PiModelDiffExplainer } from "./explain.ts";
 import { buildReviewPrompt } from "./prompt.ts";
 import { ReviewComponent } from "./review-component.ts";
 import type { DiffSource, ReviewComment, ReviewResult } from "./types.ts";
@@ -39,6 +40,7 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
             reviewLines,
             comments,
             done,
+            new PiModelDiffExplainer(ctx),
           );
         },
       );

package/src/review-component.ts

@@ -5,6 +5,11 @@ import {
   visibleWidth,
   wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import type {
+  DiffExplainer,
+  ExplanationScope,
+  ExplanationState,
+} from "./explain.ts";
 import { formatLocation } from "./prompt.ts";
 import type {
   DiffRenderMode,
@@ -14,6 +19,7 @@ import type {
   ReviewResult,
   ReviewTheme,
   ReviewTui,
+  RightPaneMode,
   SelectionBounds,
   SplitDiffCell,
   SplitDiffRow,
@@ -37,7 +43,19 @@ export class ReviewComponent {
   private selectionAnchor?: number;
   private layout: ReviewLayout = "side-by-side";
   private diffRenderMode: DiffRenderMode = "unified";
+  private rightPaneMode: RightPaneMode = "comments";
+  private explanations = new Map<string, ExplanationState>();
+  private explanationAbort?: AbortController;
+  private explanationRequestId = 0;
+  private loadingFrame = 0;
+  private loadingTimer?: ReturnType<typeof setInterval>;
   private editor: Editor;
+  private splitRows?: SplitDiffRow[];
+  private splitRowByLineIndex?: number[];
+  private lineIndexById = new Map<string, number>();
+  private commentLineKeys = new Map<number, string[]>();
+  private commentsRevision = 0;
+  private commentLineKeysRevision = -1;
 
   constructor(
     private tui: ReviewTui,
@@ -46,9 +64,11 @@ export class ReviewComponent {
     private lines: ReviewLine[],
     private comments: Map<string, ReviewComment>,
     private done: (result: ReviewResult) => void,
+    private explainer?: DiffExplainer,
   ) {
     const firstCommentable = this.lines.findIndex((line) => line.commentable);
     this.selected = firstCommentable >= 0 ? firstCommentable : 0;
+    this.lines.forEach((line, index) => this.lineIndexById.set(line.id, index));
 
     this.editor = new Editor(tui as never, {
       borderColor: (s) => theme.fg("accent", s),
@@ -71,12 +91,13 @@ export class ReviewComponent {
       const trimmed = value.trim();
       const key = this.getSelectionKey(selection.start, selection.end);
       if (!trimmed) {
-        this.comments.delete(key);
+        if (this.comments.delete(key)) this.markCommentsChanged();
       } else {
         this.comments.set(
           key,
           this.buildCommentFromSelection(selection, trimmed),
         );
+        this.markCommentsChanged();
       }
 
       this.exitEditMode();
@@ -110,6 +131,10 @@ export class ReviewComponent {
       this.toggleDiffRenderMode();
       return;
     }
+    if (data === "?") {
+      this.toggleExplanationPane();
+      return;
+    }
     if (matchesKey(data, "ctrl+d")) {
       this.move(this.getPageMoveAmount());
       return;
@@ -180,7 +205,7 @@ export class ReviewComponent {
             ? `${this.lines.length} lines • ${this.comments.size} comments • editing comment • Enter save • Esc/Ctrl+C cancel`
             : this.hasSelection()
               ? `${this.lines.length} lines • ${this.comments.size} comments • J/K extend • Esc clear selection • c comment range • Enter submit`
-              : `${this.lines.length} lines • ${this.comments.size} comments • ${this.getPositionText(selectedLine)} • j/k move • g/G top/bottom • ctrl-u/d page • t unified/split • J/K extend • c comment • x delete • n/p hunk • Enter submit • q quit`,
+              : `${this.lines.length} lines • ${this.comments.size} comments • ${this.getPositionText(selectedLine)} • j/k move • g/G top/bottom • ctrl-u/d page • t unified/split • ? explain • J/K extend • c comment • x delete • n/p hunk • Enter submit • q quit`,
         ),
         width,
       ),
@@ -276,7 +301,7 @@ export class ReviewComponent {
   }
 
   private renderSplitDiffRows(width: number, height: number): string[] {
-    const rows = this.buildSplitDiffRows();
+    const rows = this.getSplitDiffRows();
     const output: string[] = [];
     const separatorWidth = 3;
     const leftWidth = Math.max(10, Math.floor((width - separatorWidth) / 2));
@@ -344,18 +369,31 @@ export class ReviewComponent {
 
   invalidate(): void {}
 
+  dispose(): void {
+    this.explanationAbort?.abort();
+    this.stopLoadingTimer();
+  }
+
   private move(delta: number): void {
-    this.selected = Math.max(
+    const next = Math.max(
       0,
       Math.min(this.lines.length - 1, this.selected + delta),
     );
+    if (next === this.selected) return;
+    this.selected = next;
     this.tui.requestRender();
   }
 
   private jumpToBoundary(boundary: "start" | "end"): void {
-    this.selected =
-      boundary === "start" ? 0 : Math.max(0, this.lines.length - 1);
-    this.clearSelection();
+    const next = boundary === "start" ? 0 : Math.max(0, this.lines.length - 1);
+    const hadSelection = this.selectionAnchor != null;
+    if (next === this.selected && !hadSelection) return;
+    this.selected = next;
+    if (hadSelection) {
+      this.clearSelection();
+    } else {
+      this.tui.requestRender();
+    }
   }
 
   private toggleLayout(): void {
@@ -370,6 +408,15 @@ export class ReviewComponent {
     this.tui.requestRender(true);
   }
 
+  private toggleExplanationPane(): void {
+    this.rightPaneMode =
+      this.rightPaneMode === "comments" ? "explanation" : "comments";
+    if (this.rightPaneMode === "explanation") {
+      this.ensureCurrentExplanation();
+    }
+    this.tui.requestRender(true);
+  }
+
   private getPageMoveAmount(): number {
     const contentHeight = this.getContentHeight();
     const diffHeight =
@@ -383,14 +430,17 @@ export class ReviewComponent {
     if (this.selectionAnchor == null) {
       this.selectionAnchor = this.selected;
     }
-    this.selected = Math.max(
+    const next = Math.max(
       0,
       Math.min(this.lines.length - 1, this.selected + delta),
     );
+    if (next === this.selected) return;
+    this.selected = next;
     this.tui.requestRender();
   }
 
   private clearSelection(): void {
+    if (this.selectionAnchor == null) return;
     this.selectionAnchor = undefined;
     this.tui.requestRender();
   }
@@ -431,19 +481,35 @@ export class ReviewComponent {
   }
 
   private getCommentKeysForLine(index: number): string[] {
-    const line = this.lines[index];
-    if (!line) return [];
-    return [...this.comments.entries()]
-      .filter(([, comment]) => {
-        const start = this.lines.findIndex(
-          (item) => item.id === comment.startLineId,
-        );
-        const end = this.lines.findIndex(
-          (item) => item.id === comment.endLineId,
-        );
-        return start !== -1 && end !== -1 && index >= start && index <= end;
-      })
-      .map(([key]) => key);
+    this.ensureCommentLineKeys();
+    return this.commentLineKeys.get(index) ?? [];
+  }
+
+  private markCommentsChanged(): void {
+    this.commentsRevision++;
+  }
+
+  private ensureCommentLineKeys(): void {
+    if (this.commentLineKeysRevision === this.commentsRevision) return;
+
+    this.commentLineKeys = new Map<number, string[]>();
+    for (const [key, comment] of this.comments) {
+      const start = this.lineIndexById.get(comment.startLineId);
+      const end = this.lineIndexById.get(comment.endLineId);
+      if (start == null || end == null) continue;
+      const from = Math.min(start, end);
+      const to = Math.max(start, end);
+      for (let index = from; index <= to; index++) {
+        const keys = this.commentLineKeys.get(index);
+        if (keys) {
+          keys.push(key);
+        } else {
+          this.commentLineKeys.set(index, [key]);
+        }
+      }
+    }
+
+    this.commentLineKeysRevision = this.commentsRevision;
   }
 
   private buildCommentFromSelection(
@@ -503,7 +569,11 @@ export class ReviewComponent {
   private deleteComment(): void {
     const selection = this.getActiveCommentSelection();
     if (!selection) return;
-    this.comments.delete(this.getSelectionKey(selection.start, selection.end));
+    if (
+      this.comments.delete(this.getSelectionKey(selection.start, selection.end))
+    ) {
+      this.markCommentsChanged();
+    }
     this.tui.requestRender();
   }
 
@@ -532,10 +602,24 @@ export class ReviewComponent {
     this.tui.requestRender(true);
   }
 
-  private buildSplitDiffRows(): SplitDiffRow[] {
+  private getSplitDiffRows(): SplitDiffRow[] {
+    if (this.splitRows) return this.splitRows;
+
     const rows: SplitDiffRow[] = [];
+    const rowByLineIndex: number[] = [];
     let index = 0;
 
+    const pushRow = (row: SplitDiffRow) => {
+      const displayRow = rows.length;
+      rows.push(row);
+      if (row.kind === "full") {
+        rowByLineIndex[row.cell.index] = displayRow;
+      } else {
+        if (row.left) rowByLineIndex[row.left.index] = displayRow;
+        if (row.right) rowByLineIndex[row.right.index] = displayRow;
+      }
+    };
+
     while (index < this.lines.length) {
       const line = this.lines[index]!;
 
@@ -554,7 +638,7 @@ export class ReviewComponent {
 
         const count = Math.max(removals.length, additions.length);
         for (let offset = 0; offset < count; offset++) {
-          rows.push({
+          pushRow({
             kind: "split",
             left: removals[offset],
             right: additions[offset],
@@ -565,32 +649,28 @@ export class ReviewComponent {
 
       if (line.kind === "context") {
         const cell = { line, index };
-        rows.push({ kind: "split", left: cell, right: cell });
+        pushRow({ kind: "split", left: cell, right: cell });
       } else {
-        rows.push({ kind: "full", cell: { line, index } });
+        pushRow({ kind: "full", cell: { line, index } });
       }
       index++;
     }
 
+    this.splitRows = rows;
+    this.splitRowByLineIndex = rowByLineIndex;
     return rows;
   }
 
   private getSelectedDisplayRow(): number {
     if (this.diffRenderMode === "unified") return this.selected;
-    const rows = this.buildSplitDiffRows();
-    const row = rows.findIndex((item) =>
-      item.kind === "full"
-        ? item.cell.index === this.selected
-        : item.left?.index === this.selected ||
-          item.right?.index === this.selected,
-    );
-    return row === -1 ? 0 : row;
+    this.getSplitDiffRows();
+    return this.splitRowByLineIndex?.[this.selected] ?? 0;
   }
 
   private getDisplayRowCount(): number {
     return this.diffRenderMode === "unified"
       ? this.lines.length
-      : this.buildSplitDiffRows().length;
+      : this.getSplitDiffRows().length;
   }
 
   private renderSplitDiffCell(
@@ -697,6 +777,16 @@ export class ReviewComponent {
     width: number,
     height: number,
     selectedLine?: ReviewLine,
+  ): string[] {
+    return this.rightPaneMode === "explanation"
+      ? this.renderExplanationPane(width, height, selectedLine)
+      : this.renderCommentsPane(width, height, selectedLine);
+  }
+
+  private renderCommentsPane(
+    width: number,
+    height: number,
+    selectedLine?: ReviewLine,
   ): string[] {
     const lines: string[] = [];
     const title = this.theme.fg("accent", this.theme.bold("Comments"));
@@ -826,4 +916,204 @@ export class ReviewComponent {
     );
     return lines.slice(0, height);
   }
+
+  private renderExplanationPane(
+    width: number,
+    height: number,
+    selectedLine?: ReviewLine,
+  ): string[] {
+    const lines: string[] = [];
+    const title = this.theme.fg("accent", this.theme.bold("Explanation"));
+    const scope = this.getCurrentHunkScope();
+
+    lines.push(truncateToWidth(title, width));
+    lines.push(
+      truncateToWidth(
+        this.theme.fg(
+          "dim",
+          scope?.title ??
+            (selectedLine ? formatLocation(selectedLine) : "No selection"),
+        ),
+        width,
+      ),
+    );
+    lines.push("");
+
+    if (!this.explainer) {
+      lines.push(
+        ...wrapTextWithAnsi(
+          this.theme.fg("warning", "Diff explanations are unavailable."),
+          width,
+        ),
+      );
+      return lines.slice(0, height);
+    }
+
+    if (!scope) {
+      lines.push(
+        ...wrapTextWithAnsi(
+          this.theme.fg(
+            "muted",
+            "Move to a changed hunk and press ? to generate an explanation.",
+          ),
+          width,
+        ),
+      );
+      return lines.slice(0, height);
+    }
+
+    const explanation = this.explanations.get(scope.key);
+    if (!explanation) {
+      lines.push(
+        ...wrapTextWithAnsi(
+          this.theme.fg(
+            "muted",
+            "No explanation generated yet. Press ? again after returning to comments to generate this hunk.",
+          ),
+          width,
+        ),
+      );
+    } else if (explanation.status === "loading") {
+      const spinner = this.getLoadingFrame();
+      lines.push(
+        truncateToWidth(
+          this.theme.fg("accent", `${spinner} Generating explanation...`),
+          width,
+        ),
+      );
+      if (explanation.text.trim()) {
+        lines.push("");
+        lines.push(
+          ...wrapTextWithAnsi(this.theme.fg("text", explanation.text), width),
+        );
+      }
+    } else if (explanation.status === "error") {
+      lines.push(
+        ...wrapTextWithAnsi(
+          this.theme.fg(
+            "warning",
+            `Unable to explain diff: ${explanation.message}`,
+          ),
+          width,
+        ),
+      );
+    } else {
+      lines.push(
+        ...wrapTextWithAnsi(this.theme.fg("text", explanation.text), width),
+      );
+    }
+
+    lines.push("");
+    lines.push(...wrapTextWithAnsi(this.theme.fg("dim", "? comments"), width));
+    return lines.slice(0, height);
+  }
+
+  private ensureCurrentExplanation(): void {
+    const scope = this.getCurrentHunkScope();
+    if (!scope || !this.explainer) return;
+    if (this.explanations.has(scope.key)) return;
+
+    this.explanationAbort?.abort();
+    const controller = new AbortController();
+    this.explanationAbort = controller;
+    const requestId = ++this.explanationRequestId;
+    let text = "";
+
+    this.explanations.set(scope.key, { status: "loading", text });
+    this.startLoadingTimer();
+
+    void this.explainer
+      .explain(scope, {
+        signal: controller.signal,
+        onDelta: (delta) => {
+          if (requestId !== this.explanationRequestId) return;
+          text += delta;
+          this.explanations.set(scope.key, { status: "loading", text });
+          this.tui.requestRender();
+        },
+      })
+      .then((finalText) => {
+        if (requestId !== this.explanationRequestId) return;
+        this.explanations.set(scope.key, {
+          status: "ready",
+          text: finalText.trim() || text.trim() || "No explanation returned.",
+        });
+      })
+      .catch((error) => {
+        if (requestId !== this.explanationRequestId) return;
+        if (controller.signal.aborted) return;
+        this.explanations.set(scope.key, {
+          status: "error",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      })
+      .finally(() => {
+        if (requestId !== this.explanationRequestId) return;
+        this.stopLoadingTimerIfIdle();
+        this.tui.requestRender();
+      });
+
+    this.tui.requestRender();
+  }
+
+  private getCurrentHunkScope(): ExplanationScope | undefined {
+    const selectedLine = this.lines[this.selected];
+    if (!selectedLine?.filePath || !selectedLine.hunkLabel) return undefined;
+
+    let start = this.selected;
+    while (
+      start > 0 &&
+      this.lines[start - 1]?.filePath === selectedLine.filePath &&
+      this.lines[start - 1]?.hunkLabel === selectedLine.hunkLabel
+    ) {
+      start--;
+    }
+
+    let end = this.selected;
+    while (
+      end + 1 < this.lines.length &&
+      this.lines[end + 1]?.filePath === selectedLine.filePath &&
+      this.lines[end + 1]?.hunkLabel === selectedLine.hunkLabel
+    ) {
+      end++;
+    }
+
+    const diffText = this.lines
+      .slice(start, end + 1)
+      .map((line) => line.text)
+      .join("\n");
+    return {
+      key: `hunk:${selectedLine.filePath}:${selectedLine.hunkLabel}:${start}:${end}`,
+      kind: "hunk",
+      title: `${selectedLine.filePath} ${selectedLine.hunkLabel}`,
+      filePath: selectedLine.filePath,
+      diffText,
+    };
+  }
+
+  private getLoadingFrame(): string {
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    return frames[this.loadingFrame % frames.length] ?? "⠋";
+  }
+
+  private startLoadingTimer(): void {
+    if (this.loadingTimer) return;
+    this.loadingTimer = setInterval(() => {
+      this.loadingFrame++;
+      this.tui.requestRender();
+    }, 120);
+  }
+
+  private stopLoadingTimerIfIdle(): void {
+    const hasLoading = [...this.explanations.values()].some(
+      (explanation) => explanation.status === "loading",
+    );
+    if (!hasLoading) this.stopLoadingTimer();
+  }
+
+  private stopLoadingTimer(): void {
+    if (!this.loadingTimer) return;
+    clearInterval(this.loadingTimer);
+    this.loadingTimer = undefined;
+  }
 }

package/src/types.ts

@@ -59,3 +59,5 @@ export type ReviewTui = {
 };
 
 export type ReviewTheme = Theme;
+
+export type RightPaneMode = "comments" | "explanation";