pi-diff-review 0.1.12 → 0.1.14

package/README.md

@@ -2,9 +2,9 @@
 
 # pi-diff-review
 
-Embedded code reviews directly directly within [pi](https://pi.dev/).
+Embedded code reviews and AI summaries directly within [pi](https://pi.dev/).
 
-<img width="1986" height="1556" alt="pi-diff-review-screenshot(1)" src="https://github.com/user-attachments/assets/3fd00163-5d19-489b-94ed-3d4816c6cad3" />
+<img width="1986" height="1556" alt="pi-diff-review-screenshot" src="https://github.com/user-attachments/assets/5ddd7226-28d4-4617-8c5c-35b4b6af68dc" />
 
 ## Install
 
@@ -27,14 +27,46 @@ git clone https://github.com/cmpadden/pi-diff-review
 pi install ./pi-diff-review
 ```
 
+## Usage
+
+Start a review with `/diff`. By default, this reviews your current unstaged changes:
+
+```text
+/diff
+```
+
+Review staged changes with `--cached`:
+
+```text
+/diff --cached
+```
+
+Review a branch or commit range by passing any `git diff` arguments after `/diff`:
+
+```text
+/diff main...HEAD
+```
+
+`/diff <git-diff-args>` is passed through to `git diff`, so these examples are equivalent to running `git diff`, `git diff --cached`, and `git diff main...HEAD` locally before opening the review UI.
+
+### Staged vs. unstaged changes
+
+- `/diff` shows unstaged working-tree changes only.
+- `/diff --cached` shows staged changes only.
+- If you have both staged and unstaged edits, run both commands separately to review each set.
+- To review everything relative to a base branch, use a range such as `/diff main...HEAD`.
+
 ## Features
 
 - `/diff` reviews the current unstaged `git diff`
-- `/diff <git-diff-args>` passes arguments through to `git diff` (for example `/diff main...HEAD`)
+- `/diff --cached` reviews staged changes
+- `/diff main...HEAD` reviews changes on the current branch relative to `main`
+- `/diff <git-diff-args>` passes arguments through to `git diff`
 - `j/k` or arrow keys to move
 - `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
+- `t` toggles inline comments/explanations
+- `v` 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-diff-review",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Local diff review TUI extension for pi",
   "license": "MIT",
   "type": "module",

package/src/comment-manager.ts

@@ -0,0 +1,73 @@
+import type { ReviewComment, ReviewLine, SelectionBounds } from "./types.ts";
+
+export const GLOBAL_COMMENT_KEY = "__global_diff_comment__";
+
+export function getSelectionKey(
+  lines: ReviewLine[],
+  start: number,
+  end: number,
+): string {
+  return `${lines[start]?.id ?? start}:${lines[end]?.id ?? end}`;
+}
+
+export function buildGlobalComment(text: string): ReviewComment {
+  return {
+    id: GLOBAL_COMMENT_KEY,
+    filePath: "Overall diff",
+    text,
+    global: true,
+    startLineId: GLOBAL_COMMENT_KEY,
+    endLineId: GLOBAL_COMMENT_KEY,
+    lineText: "",
+  };
+}
+
+export function buildCommentFromSelection(
+  lines: ReviewLine[],
+  selection: SelectionBounds,
+  text: string,
+): ReviewComment {
+  const startLine = lines[selection.start]!;
+  const endLine = lines[selection.end]!;
+  const excerpt = lines
+    .slice(selection.start, selection.end + 1)
+    .map((line) => line.text)
+    .join("\n");
+  return {
+    id: getSelectionKey(lines, selection.start, selection.end),
+    filePath: startLine.filePath ?? endLine.filePath ?? "(unknown file)",
+    text,
+    startLineId: startLine.id,
+    endLineId: endLine.id,
+    startOldLineNumber: startLine.oldLineNumber,
+    startNewLineNumber: startLine.newLineNumber,
+    endOldLineNumber: endLine.oldLineNumber,
+    endNewLineNumber: endLine.newLineNumber,
+    lineText: excerpt,
+  };
+}
+
+export function buildCommentLineKeys(
+  comments: Map<string, ReviewComment>,
+  lineIndexById: Map<string, number>,
+): Map<number, string[]> {
+  const commentLineKeys = new Map<number, string[]>();
+
+  for (const [key, comment] of comments) {
+    const start = lineIndexById.get(comment.startLineId);
+    const end = 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 = commentLineKeys.get(index);
+      if (keys) {
+        keys.push(key);
+      } else {
+        commentLineKeys.set(index, [key]);
+      }
+    }
+  }
+
+  return commentLineKeys;
+}

package/src/diff-source.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import type { DiffSource } from "./types.ts";
 
 export function parseDiffSource(args: string): DiffSource {
@@ -64,14 +64,40 @@ function tokenizeDiffArgs(input: string): string[] {
   return args;
 }
 
+export const DIFF_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+
 export function getDiff(cwd: string, source: DiffSource): string {
-  return execFileSync(
-    "git",
-    ["diff", "--no-color", "--unified=3", ...source.args],
-    {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-    },
-  );
+  const args = ["diff", "--no-color", "--unified=3", ...source.args];
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: DIFF_MAX_BUFFER_BYTES,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (result.error) {
+    throw new Error(formatSpawnError(result.error));
+  }
+
+  if (result.status !== 0) {
+    const stderr = result.stderr.trim();
+    throw new Error(
+      stderr || `git ${args.join(" ")} exited with status ${result.status}.`,
+    );
+  }
+
+  return result.stdout;
+}
+
+function formatSpawnError(error: Error & { code?: string }): string {
+  if (error.code === "ENOBUFS") {
+    return `Diff output exceeded the ${formatBytes(DIFF_MAX_BUFFER_BYTES)} safety limit. Try reviewing a smaller diff or narrowing with git diff pathspecs.`;
+  }
+
+  return error.message;
+}
+
+function formatBytes(bytes: number): string {
+  const mib = bytes / 1024 / 1024;
+  return `${Number.isInteger(mib) ? mib : mib.toFixed(1)} MiB`;
 }

package/src/explanation-controller.ts

@@ -0,0 +1,167 @@
+import type {
+  DiffExplainer,
+  ExplanationScope,
+  ExplanationState,
+} from "./explain.ts";
+import type { ReviewLine, ReviewTui } from "./types.ts";
+
+const LOADING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export function getCurrentHunkScope(
+  lines: ReviewLine[],
+  selected: number,
+): ExplanationScope | undefined {
+  const selectedLine = lines[selected];
+  if (!selectedLine?.filePath || !selectedLine.hunkLabel) return undefined;
+
+  let start = selected;
+  while (
+    start > 0 &&
+    lines[start - 1]?.filePath === selectedLine.filePath &&
+    lines[start - 1]?.hunkLabel === selectedLine.hunkLabel
+  ) {
+    start--;
+  }
+
+  let end = selected;
+  while (
+    end + 1 < lines.length &&
+    lines[end + 1]?.filePath === selectedLine.filePath &&
+    lines[end + 1]?.hunkLabel === selectedLine.hunkLabel
+  ) {
+    end++;
+  }
+
+  const diffText = 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,
+  };
+}
+
+export class ExplanationController {
+  readonly explanations = new Map<string, ExplanationState>();
+  private abortController?: AbortController;
+  private requestId = 0;
+  private loadingFrame = 0;
+  private loadingTimer?: ReturnType<typeof setInterval>;
+
+  constructor(
+    private readonly tui: ReviewTui,
+    private readonly explainer?: DiffExplainer,
+    cachedExplanations: Map<string, string> = new Map(),
+    private readonly onExplanationsChanged?: (
+      explanations: Map<string, string>,
+    ) => void,
+  ) {
+    for (const [key, text] of cachedExplanations) {
+      const trimmed = text.trim();
+      if (trimmed)
+        this.explanations.set(key, { status: "ready", text: trimmed });
+    }
+  }
+
+  get isAvailable(): boolean {
+    return this.explainer != null;
+  }
+
+  getState(scope: ExplanationScope | undefined): ExplanationState | undefined {
+    return scope ? this.explanations.get(scope.key) : undefined;
+  }
+
+  getLoadingFrame(): string {
+    return LOADING_FRAMES[this.loadingFrame % LOADING_FRAMES.length] ?? "⠋";
+  }
+
+  ensure(scope: ExplanationScope | undefined): void {
+    if (!scope || !this.explainer) return;
+    if (this.explanations.has(scope.key)) return;
+
+    this.abortController?.abort();
+    const controller = new AbortController();
+    this.abortController = controller;
+    const requestId = ++this.requestId;
+    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.requestId) return;
+          text += delta;
+          this.explanations.set(scope.key, { status: "loading", text });
+          this.tui.requestRender();
+        },
+      })
+      .then((finalText) => {
+        if (requestId !== this.requestId) return;
+        this.explanations.set(scope.key, {
+          status: "ready",
+          text: finalText.trim() || text.trim() || "No explanation returned.",
+        });
+        this.emitExplanationsChanged();
+      })
+      .catch((error) => {
+        if (requestId !== this.requestId) 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.requestId) return;
+        this.stopLoadingTimerIfIdle();
+        this.tui.requestRender();
+      });
+
+    this.tui.requestRender();
+  }
+
+  dispose(): void {
+    this.abortController?.abort();
+    this.stopLoadingTimer();
+  }
+
+  private emitExplanationsChanged(): void {
+    if (!this.onExplanationsChanged) return;
+
+    const readyExplanations = new Map<string, string>();
+    for (const [key, explanation] of this.explanations) {
+      if (explanation.status === "ready") {
+        readyExplanations.set(key, explanation.text);
+      }
+    }
+    this.onExplanationsChanged(readyExplanations);
+  }
+
+  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/index.ts

@@ -11,6 +11,7 @@ import { ReviewComponent } from "./review-component.ts";
 import type { DiffSource, ReviewComment, ReviewResult } from "./types.ts";
 
 const DIFF_REVIEW_CACHE_ENTRY = "pi-diff-review-cache";
+const DIFF_REVIEW_EXPLANATION_CACHE_ENTRY = "pi-diff-review-explanation-cache";
 
 type DiffReviewCacheEntry = {
   cacheKey: string;
@@ -18,6 +19,12 @@ type DiffReviewCacheEntry = {
   updatedAt: number;
 };
 
+type DiffExplanationCacheEntry = {
+  cacheKey: string;
+  explanations: Record<string, string>;
+  updatedAt: number;
+};
+
 function getDiffCacheKey(
   cwd: string,
   source: DiffSource,
@@ -71,6 +78,58 @@ function persistCachedComments(
   } satisfies DiffReviewCacheEntry);
 }
 
+function getCachedExplanations(
+  ctx: ExtensionCommandContext,
+  cacheKey: string,
+): Map<string, string> {
+  let latest: DiffExplanationCacheEntry | undefined;
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (
+      entry.type !== "custom" ||
+      entry.customType !== DIFF_REVIEW_EXPLANATION_CACHE_ENTRY
+    ) {
+      continue;
+    }
+
+    const data = entry.data as Partial<DiffExplanationCacheEntry> | undefined;
+    if (
+      data?.cacheKey !== cacheKey ||
+      !data.explanations ||
+      typeof data.explanations !== "object" ||
+      Array.isArray(data.explanations)
+    ) {
+      continue;
+    }
+
+    if (!latest || (data.updatedAt ?? 0) >= latest.updatedAt) {
+      latest = {
+        cacheKey: data.cacheKey,
+        explanations: Object.fromEntries(
+          Object.entries(data.explanations).filter(
+            (entry): entry is [string, string] =>
+              typeof entry[0] === "string" && typeof entry[1] === "string",
+          ),
+        ),
+        updatedAt: data.updatedAt ?? 0,
+      };
+    }
+  }
+
+  return new Map(Object.entries(latest?.explanations ?? {}));
+}
+
+function persistCachedExplanations(
+  pi: ExtensionAPI,
+  cacheKey: string,
+  explanations: Map<string, string>,
+): void {
+  pi.appendEntry(DIFF_REVIEW_EXPLANATION_CACHE_ENTRY, {
+    cacheKey,
+    explanations: Object.fromEntries(explanations),
+    updatedAt: Date.now(),
+  } satisfies DiffExplanationCacheEntry);
+}
+
 export function registerDiffReviewCommand(pi: ExtensionAPI): void {
   pi.registerCommand("diff", {
     description: "Review a git diff in a custom TUI (/diff [git diff args])",
@@ -94,12 +153,19 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
       const reviewLines = parseDiff(diffText);
       const cacheKey = getDiffCacheKey(ctx.cwd, source, diffText);
       const comments = getCachedComments(ctx, cacheKey);
+      const explanations = getCachedExplanations(ctx, cacheKey);
       if (comments.size > 0) {
         ctx.ui.notify(
           `Restored ${comments.size} cached diff comment${comments.size === 1 ? "" : "s"}.`,
           "info",
         );
       }
+      if (explanations.size > 0) {
+        ctx.ui.notify(
+          `Restored ${explanations.size} cached hunk explanation${explanations.size === 1 ? "" : "s"}.`,
+          "info",
+        );
+      }
 
       const result = await ctx.ui.custom<ReviewResult>(
         (tui, theme, _keybindings, done) => {
@@ -114,6 +180,10 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
             (updatedComments) => {
               persistCachedComments(pi, cacheKey, updatedComments.values());
             },
+            explanations,
+            (updatedExplanations) => {
+              persistCachedExplanations(pi, cacheKey, updatedExplanations);
+            },
           );
         },
       );

package/src/prompt.ts

@@ -17,7 +17,7 @@ export function formatLocation(line: {
   return file;
 }
 
-function formatCommentLocation(comment: ReviewComment): string {
+export function formatCommentLocation(comment: ReviewComment): string {
   if (comment.global) return "Overall diff";
 
   const start = formatLocation({

package/src/render-utils.ts

@@ -0,0 +1,11 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export function padToWidth(text: string, width: number): string {
+  const visible = visibleWidth(text);
+  if (visible >= width) return truncateToWidth(text, width);
+  return text + " ".repeat(width - visible);
+}
+
+export function lineNumberCell(value?: number): string {
+  return value == null ? "    " : String(value).padStart(4, " ");
+}