pi-diff-review 0.1.11 → 0.1.13

package/README.md

@@ -20,14 +20,53 @@ Or install directly from GitHub:
 pi install https://github.com/cmpadden/pi-diff-review
 ```
 
+For local development, clone the repository and install from the local path:
+
+```bash
+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 the comments/explanation sidebar
+- `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
@@ -39,6 +78,21 @@ pi install https://github.com/cmpadden/pi-diff-review
 - Comments are cached per session and restored when reopening the same diff
 - `q` to exit
 
+## Development
+
+Install [pre-commit](https://pre-commit.com/) and enable the repository hooks to run typechecking, tests, and formatting checks before each commit:
+
+```bash
+pre-commit install
+```
+
+Run the same checks manually with either:
+
+```bash
+pre-commit run --all-files
+npm run precommit
+```
+
 ## Release
 
 See [RELEASE.md](./RELEASE.md).

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "pi-diff-review",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Local diff review TUI extension for pi",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cmpadden/pi-diff-review.git"
@@ -26,16 +27,30 @@
     "LICENSE"
   ],
   "scripts": {
-    "format": "prettier --write ."
+    "check": "npm run typecheck && npm test",
+    "format": "prettier --write .",
+    "precommit": "npm run check && npx prettier --check .",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "prettier": "^3.5.3"
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.1",
+    "@earendil-works/pi-tui": "^0.74.1",
+    "@types/node": "^24.12.4",
+    "prettier": "^3.5.3",
+    "tsx": "^4.22.1",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
@@ -46,10 +61,10 @@
   "pi": {
     "extensions": [
       "./extensions"
-    ]
+    ],
+    "image": "https://github.com/user-attachments/assets/3fd00163-5d19-489b-94ed-3d4816c6cad3"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
     "@pierre/diffs": "^1.1.21"
   }
 }

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/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, " ");
+}