pi-diff-review 0.1.6 → 0.1.8

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,10 +28,12 @@ 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
 - `c` to add or edit a comment for the current line or selected range
+- `C` to add or edit an overall diff comment
 - `x` to delete a comment for the current line or selected range
 - `Enter` to submit comments back to pi
 - `q` to exit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-diff-review",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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/prompt.ts

@@ -18,6 +18,8 @@ export function formatLocation(line: {
 }
 
 function formatCommentLocation(comment: ReviewComment): string {
+  if (comment.global) return "Overall diff";
+
   const start = formatLocation({
     filePath: comment.filePath,
     oldLineNumber: comment.startOldLineNumber,

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,
@@ -29,6 +35,8 @@ function lineNumberCell(value?: number): string {
   return value == null ? "    " : String(value).padStart(4, " ");
 }
 
+const GLOBAL_COMMENT_KEY = "__global_diff_comment__";
+
 export class ReviewComponent {
   private selected = 0;
   private scrollTop = 0;
@@ -37,6 +45,12 @@ 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[];
@@ -52,6 +66,7 @@ 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;
@@ -69,13 +84,28 @@ export class ReviewComponent {
     });
 
     this.editor.onSubmit = (value) => {
+      const trimmed = value.trim();
+      if (this.editingCommentKey === GLOBAL_COMMENT_KEY) {
+        if (!trimmed) {
+          if (this.comments.delete(GLOBAL_COMMENT_KEY))
+            this.markCommentsChanged();
+        } else {
+          this.comments.set(
+            GLOBAL_COMMENT_KEY,
+            this.buildGlobalComment(trimmed),
+          );
+          this.markCommentsChanged();
+        }
+        this.exitEditMode();
+        return;
+      }
+
       const selection = this.getActiveCommentSelection();
       if (!selection) {
         this.exitEditMode();
         return;
       }
 
-      const trimmed = value.trim();
       const key = this.getSelectionKey(selection.start, selection.end);
       if (!trimmed) {
         if (this.comments.delete(key)) this.markCommentsChanged();
@@ -118,6 +148,10 @@ export class ReviewComponent {
       this.toggleDiffRenderMode();
       return;
     }
+    if (data === "?") {
+      this.toggleExplanationPane();
+      return;
+    }
     if (matchesKey(data, "ctrl+d")) {
       this.move(this.getPageMoveAmount());
       return;
@@ -166,6 +200,10 @@ export class ReviewComponent {
       this.startEditMode();
       return;
     }
+    if (data === "C") {
+      this.startGlobalEditMode();
+      return;
+    }
     if (matchesKey(data, "enter")) {
       const comments = [...this.comments.values()].sort((a, b) =>
         a.id.localeCompare(b.id),
@@ -187,8 +225,8 @@ export class ReviewComponent {
           this.editMode
             ? `${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 • J/K extend • Esc clear selection • c comment range • C overall comment • 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 • ? explain • J/K extend • c comment • C overall • x delete • n/p hunk • Enter submit • q quit`,
         ),
         width,
       ),
@@ -352,6 +390,11 @@ export class ReviewComponent {
 
   invalidate(): void {}
 
+  dispose(): void {
+    this.explanationAbort?.abort();
+    this.stopLoadingTimer();
+  }
+
   private move(delta: number): void {
     const next = Math.max(
       0,
@@ -386,6 +429,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 =
@@ -481,6 +533,18 @@ export class ReviewComponent {
     this.commentLineKeysRevision = this.commentsRevision;
   }
 
+  private buildGlobalComment(text: string): ReviewComment {
+    return {
+      id: GLOBAL_COMMENT_KEY,
+      filePath: "Overall diff",
+      text,
+      global: true,
+      startLineId: GLOBAL_COMMENT_KEY,
+      endLineId: GLOBAL_COMMENT_KEY,
+      lineText: "",
+    };
+  }
+
   private buildCommentFromSelection(
     selection: SelectionBounds,
     text: string,
@@ -546,6 +610,15 @@ export class ReviewComponent {
     this.tui.requestRender();
   }
 
+  private startGlobalEditMode(): void {
+    const existing = this.comments.get(GLOBAL_COMMENT_KEY);
+    this.rightPaneMode = "comments";
+    this.editMode = true;
+    this.editingCommentKey = GLOBAL_COMMENT_KEY;
+    this.editor.setText(existing?.text ?? "");
+    this.tui.requestRender(true);
+  }
+
   private startEditMode(): void {
     const selection = this.getActiveCommentSelection();
     if (!selection) return;
@@ -555,6 +628,7 @@ export class ReviewComponent {
     if (startLine.filePath !== endLine.filePath) return;
 
     const existing = this.getCommentForSelection(selection);
+    this.rightPaneMode = "comments";
     this.editMode = true;
     this.editingCommentKey = this.getSelectionKey(
       selection.start,
@@ -746,6 +820,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"));
@@ -768,6 +852,42 @@ export class ReviewComponent {
     );
     lines.push("");
 
+    if (this.editMode && this.editingCommentKey === GLOBAL_COMMENT_KEY) {
+      lines[1] = truncateToWidth(
+        this.theme.fg("dim", "Overall diff comment"),
+        width,
+      );
+      lines.push(
+        ...wrapTextWithAnsi(
+          this.theme.fg(
+            "dim",
+            "Editing overall diff comment. Enter saves. Esc or Ctrl+C cancels.",
+          ),
+          width,
+        ),
+      );
+      lines.push("");
+      for (const line of this.editor.render(Math.max(10, width))) {
+        lines.push(truncateToWidth(line, width));
+      }
+      return lines.slice(0, height);
+    }
+
+    const globalComment = this.comments.get(GLOBAL_COMMENT_KEY);
+    if (globalComment) {
+      lines.push(
+        truncateToWidth(
+          this.theme.fg("accent", this.theme.bold("Overall diff comment")),
+          width,
+        ),
+      );
+      lines.push(
+        ...wrapTextWithAnsi(this.theme.fg("text", globalComment.text), width),
+      );
+      lines.push(...wrapTextWithAnsi(this.theme.fg("dim", "C edits"), width));
+      lines.push("");
+    }
+
     if (!selectedLine) {
       lines.push(
         ...wrapTextWithAnsi(
@@ -783,7 +903,7 @@ export class ReviewComponent {
         ...wrapTextWithAnsi(
           this.theme.fg(
             "muted",
-            "Move to a diff line and press c to add a comment.",
+            "Move to a diff line and press c to add a comment, or press C for an overall diff comment.",
           ),
           width,
         ),
@@ -848,8 +968,8 @@ export class ReviewComponent {
           this.theme.fg(
             "dim",
             this.hasSelection()
-              ? "Press c to add a range comment."
-              : "Press c to add one. Use J/K to extend a range.",
+              ? "Press c to add a range comment, or C for an overall diff comment."
+              : "Press c to add one. Use J/K to extend a range. Press C for an overall diff comment.",
           ),
           width,
         ),
@@ -875,4 +995,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

@@ -6,6 +6,7 @@ export type ReviewComment = {
   id: string;
   filePath: string;
   text: string;
+  global?: boolean;
   startLineId: string;
   endLineId: string;
   startOldLineNumber?: number;
@@ -59,3 +60,5 @@ export type ReviewTui = {
 };
 
 export type ReviewTheme = Theme;
+
+export type RightPaneMode = "comments" | "explanation";