pi-diff-review 0.1.17 → 0.1.19

package/package.json

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

package/src/explanation/controller.ts

@@ -49,6 +49,9 @@ export class ExplanationController {
   readonly explanations = new Map<string, ExplanationState>();
   private abortController?: AbortController;
   private requestId = 0;
+  private askState: ExplanationState | undefined;
+  private askAbortController?: AbortController;
+  private askRequestId = 0;
   private loadingFrame = 0;
   private loadingTimer?: ReturnType<typeof setInterval>;
 
@@ -59,12 +62,19 @@ export class ExplanationController {
     private readonly onExplanationsChanged?: (
       explanations: Map<string, string>,
     ) => void,
+    cachedAskText?: string,
+    private readonly onAskChanged?: (state?: ExplanationState) => void,
   ) {
     for (const [key, text] of cachedExplanations) {
       const trimmed = text.trim();
       if (trimmed)
         this.explanations.set(key, { status: "ready", text: trimmed });
     }
+
+    const trimmedAskText = cachedAskText?.trim();
+    if (trimmedAskText) {
+      this.askState = { status: "ready", text: trimmedAskText };
+    }
   }
 
   get isAvailable(): boolean {
@@ -79,6 +89,65 @@ export class ExplanationController {
     return LOADING_FRAMES[this.loadingFrame % LOADING_FRAMES.length] ?? "⠋";
   }
 
+  ask(scope: ExplanationScope, question: string): void {
+    if (!this.explainer) return;
+    this.askAbortController?.abort();
+    const controller = new AbortController();
+    this.askAbortController = controller;
+    const requestId = ++this.askRequestId;
+    let text = "";
+    this.askState = { status: "loading", text };
+    this.onAskChanged?.(this.askState);
+    this.startLoadingTimer();
+
+    void this.explainer
+      .explain(scope, question, {
+        signal: controller.signal,
+        onDelta: (delta) => {
+          if (requestId !== this.askRequestId) return;
+          text += delta;
+          this.askState = { status: "loading", text };
+          this.onAskChanged?.(this.askState);
+          this.tui.requestRender();
+        },
+      })
+      .then((finalText) => {
+        if (requestId !== this.askRequestId) return;
+        this.askState = {
+          status: "ready",
+          text: finalText.trim() || text.trim() || "No answer returned.",
+        };
+        this.onAskChanged?.(this.askState);
+      })
+      .catch((error) => {
+        if (requestId !== this.askRequestId) return;
+        if (controller.signal.aborted) return;
+        this.askState = {
+          status: "error",
+          message: error instanceof Error ? error.message : String(error),
+        };
+        this.onAskChanged?.(this.askState);
+      })
+      .finally(() => {
+        if (requestId !== this.askRequestId) return;
+        this.stopLoadingTimerIfIdle();
+        this.tui.requestRender();
+      });
+
+    this.tui.requestRender();
+  }
+
+  getAskState(): ExplanationState | undefined {
+    return this.askState;
+  }
+
+  clearAsk(): void {
+    this.askAbortController?.abort();
+    this.askAbortController = undefined;
+    this.askState = undefined;
+    this.onAskChanged?.(undefined);
+  }
+
   ensure(scope: ExplanationScope | undefined): void {
     if (!scope || !this.explainer) return;
     if (this.explanations.has(scope.key)) return;
@@ -93,7 +162,7 @@ export class ExplanationController {
     this.startLoadingTimer();
 
     void this.explainer
-      .explain(scope, {
+      .explain(scope, undefined, {
         signal: controller.signal,
         onDelta: (delta) => {
           if (requestId !== this.requestId) return;
@@ -129,6 +198,7 @@ export class ExplanationController {
 
   dispose(): void {
     this.abortController?.abort();
+    this.askAbortController?.abort();
     this.stopLoadingTimer();
   }
 
@@ -153,9 +223,9 @@ export class ExplanationController {
   }
 
   private stopLoadingTimerIfIdle(): void {
-    const hasLoading = [...this.explanations.values()].some(
-      (explanation) => explanation.status === "loading",
-    );
+    const hasLoading =
+      [...this.explanations.values()].some((e) => e.status === "loading") ||
+      this.askState?.status === "loading";
     if (!hasLoading) this.stopLoadingTimer();
   }
 

package/src/explanation/explainer.ts

@@ -18,6 +18,7 @@ export type ExplanationState =
 export type DiffExplainer = {
   explain(
     scope: ExplanationScope,
+    question?: string,
     options?: {
       signal?: AbortSignal;
       onDelta?: (delta: string) => void;
@@ -25,6 +26,13 @@ export type DiffExplainer = {
   ): Promise<string>;
 };
 
+export function buildAskPrompt(
+  scope: ExplanationScope,
+  question: string,
+): string {
+  return `Given this git diff hunk:\n\`\`\`diff\n${scope.diffText}\n\`\`\`\n\n${question}`;
+}
+
 export function buildExplanationPrompt(scope: ExplanationScope): string {
   return `Explain this git diff hunk for a code reviewer.
 
@@ -46,6 +54,7 @@ export class PiModelDiffExplainer implements DiffExplainer {
 
   async explain(
     scope: ExplanationScope,
+    question?: string,
     options: {
       signal?: AbortSignal;
       onDelta?: (delta: string) => void;
@@ -67,7 +76,9 @@ export class PiModelDiffExplainer implements DiffExplainer {
       messages: [
         {
           role: "user",
-          content: buildExplanationPrompt(scope),
+          content: question
+            ? buildAskPrompt(scope, question)
+            : buildExplanationPrompt(scope),
           timestamp: Date.now(),
         },
       ],

package/src/index.ts

@@ -10,12 +10,14 @@ import { buildReviewPrompt } from "./review/prompt.ts";
 import { ReviewComponent } from "./review/component.ts";
 import type {
   DiffSource,
+  PersistedAsk,
   ReviewComment,
   ReviewResult,
 } from "./review/types.ts";
 
 const DIFF_REVIEW_CACHE_ENTRY = "pi-diff-review-cache";
 const DIFF_REVIEW_EXPLANATION_CACHE_ENTRY = "pi-diff-review-explanation-cache";
+const DIFF_REVIEW_ASK_CACHE_ENTRY = "pi-diff-review-ask-cache";
 
 type DiffReviewCacheEntry = {
   cacheKey: string;
@@ -29,6 +31,12 @@ type DiffExplanationCacheEntry = {
   updatedAt: number;
 };
 
+type DiffAskCacheEntry = {
+  cacheKey: string;
+  ask?: PersistedAsk;
+  updatedAt: number;
+};
+
 function getDiffCacheKey(
   cwd: string,
   source: DiffSource,
@@ -134,6 +142,56 @@ function persistCachedExplanations(
   } satisfies DiffExplanationCacheEntry);
 }
 
+function getCachedAsk(
+  ctx: ExtensionCommandContext,
+  cacheKey: string,
+): PersistedAsk | undefined {
+  let latest: DiffAskCacheEntry | undefined;
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (
+      entry.type !== "custom" ||
+      entry.customType !== DIFF_REVIEW_ASK_CACHE_ENTRY
+    ) {
+      continue;
+    }
+
+    const data = entry.data as Partial<DiffAskCacheEntry> | undefined;
+    if (data?.cacheKey !== cacheKey) continue;
+
+    const ask = data.ask;
+    const validAsk =
+      ask &&
+      typeof ask === "object" &&
+      typeof ask.scopeKey === "string" &&
+      typeof ask.anchorLineId === "string" &&
+      typeof ask.text === "string"
+        ? ask
+        : undefined;
+
+    if (!latest || (data.updatedAt ?? 0) >= latest.updatedAt) {
+      latest = {
+        cacheKey: data.cacheKey,
+        ask: validAsk,
+        updatedAt: data.updatedAt ?? 0,
+      };
+    }
+  }
+
+  return latest?.ask;
+}
+
+function persistCachedAsk(
+  pi: ExtensionAPI,
+  cacheKey: string,
+  ask?: PersistedAsk,
+): void {
+  pi.appendEntry(DIFF_REVIEW_ASK_CACHE_ENTRY, {
+    cacheKey,
+    ask,
+    updatedAt: Date.now(),
+  } satisfies DiffAskCacheEntry);
+}
+
 export function registerDiffReviewCommand(pi: ExtensionAPI): void {
   pi.registerCommand("diff", {
     description: "Review a git diff in a custom TUI (/diff [git diff args])",
@@ -158,6 +216,7 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
       const cacheKey = getDiffCacheKey(ctx.cwd, source, diffText);
       const comments = getCachedComments(ctx, cacheKey);
       const explanations = getCachedExplanations(ctx, cacheKey);
+      const ask = getCachedAsk(ctx, cacheKey);
       if (comments.size > 0) {
         ctx.ui.notify(
           `Restored ${comments.size} cached diff comment${comments.size === 1 ? "" : "s"}.`,
@@ -170,6 +229,9 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
           "info",
         );
       }
+      if (ask) {
+        ctx.ui.notify("Restored cached ask answer.", "info");
+      }
 
       const result = await ctx.ui.custom<ReviewResult>(
         (tui, theme, _keybindings, done) => {
@@ -188,6 +250,10 @@ export function registerDiffReviewCommand(pi: ExtensionAPI): void {
             (updatedExplanations) => {
               persistCachedExplanations(pi, cacheKey, updatedExplanations);
             },
+            ask,
+            (updatedAsk) => {
+              persistCachedAsk(pi, cacheKey, updatedAsk);
+            },
           );
         },
       );

package/src/review/component.ts

@@ -9,7 +9,11 @@ import {
   visibleWidth,
   wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
-import type { DiffExplainer } from "../explanation/explainer.ts";
+import type {
+  DiffExplainer,
+  ExplanationScope,
+  ExplanationState,
+} from "../explanation/explainer.ts";
 import {
   GLOBAL_COMMENT_KEY,
   buildCommentFromSelection,
@@ -28,6 +32,7 @@ import { padToWidth, lineNumberCell } from "../render/utils.ts";
 import { buildSplitDiffRows } from "../diff/split.ts";
 import type {
   DiffRenderMode,
+  PersistedAsk,
   ReviewComment,
   ReviewLine,
   ReviewResult,
@@ -54,6 +59,7 @@ type AnnotatedDiffRow =
 const HELP_COMMANDS = [
   ["h", "show or hide this help"],
   ["j/k or arrows", "move selection"],
+  ["PgUp / PgDown", "move up or down half a page"],
   ["ctrl-u / ctrl-d", "move up or down half a page"],
   ["g / G", "jump to top or bottom"],
   ["n / p", "jump to next or previous hunk"],
@@ -66,6 +72,7 @@ const HELP_COMMANDS = [
   ["t", "toggle inline comments and explanations"],
   ["v", "toggle unified or split rendering"],
   ["?", "toggle AI explanation for current hunk"],
+  ["a", "ask a question about the current hunk"],
   ["Enter", "submit comments, save edits, or jump to search result"],
   ["Esc", "close help, cancel search/edit, clear selection, or exit"],
   ["q", "exit review"],
@@ -80,6 +87,10 @@ export class ReviewComponent {
 
   private inlineAnnotationsVisible = true;
   private visibleExplanationKeys = new Set<string>();
+  private explanationAnchorByScope = new Map<string, number>();
+  private askInputMode = false;
+  private askScope?: ExplanationScope;
+  private askAnchorIndex?: number;
   private explanationController: ExplanationController;
   private editor: Editor;
   private splitRows?: SplitDiffRow[];
@@ -109,6 +120,8 @@ export class ReviewComponent {
     private onCommentsChanged?: (comments: Map<string, ReviewComment>) => void,
     cachedExplanations?: Map<string, string>,
     private onExplanationsChanged?: (explanations: Map<string, string>) => void,
+    cachedAsk?: PersistedAsk,
+    private onAskChanged?: (ask?: PersistedAsk) => void,
   ) {
     const firstCommentable = this.lines.findIndex((line) => line.commentable);
     this.navigation = new ReviewNavigationState(
@@ -117,11 +130,36 @@ export class ReviewComponent {
     );
     this.lines.forEach((line, index) => this.lineIndexById.set(line.id, index));
     this.search = new ReviewSearchState(this.lines);
+
+    const restoredAsk = cachedAsk
+      ? this.restorePersistedAsk(cachedAsk)
+      : undefined;
+    if (restoredAsk) {
+      this.askScope = restoredAsk.scope;
+      this.askAnchorIndex = restoredAsk.anchorIndex;
+    }
+
     this.explanationController = new ExplanationController(
       tui,
       explainer,
       cachedExplanations,
       onExplanationsChanged,
+      restoredAsk ? cachedAsk?.text : undefined,
+      (state) => {
+        if (!state) {
+          this.onAskChanged?.(undefined);
+          return;
+        }
+        if (state.status !== "ready") return;
+        if (!this.askScope || this.askAnchorIndex == null) return;
+        const anchorLine = this.lines[this.askAnchorIndex];
+        if (!anchorLine) return;
+        this.onAskChanged?.({
+          scopeKey: this.askScope.key,
+          anchorLineId: anchorLine.id,
+          text: state.text,
+        });
+      },
     );
 
     this.editor = new Editor(tui as never, {
@@ -136,6 +174,20 @@ export class ReviewComponent {
     });
 
     this.editor.onSubmit = (value) => {
+      if (this.askInputMode) {
+        this.askInputMode = false;
+        this.editor.setText("");
+        const question = value.trim();
+        if (question && this.askScope) {
+          this.explanationController.ask(this.askScope, question);
+        } else {
+          this.askScope = undefined;
+          this.askAnchorIndex = undefined;
+        }
+        this.invalidateAnnotatedRows();
+        this.tui.requestRender(true);
+        return;
+      }
       const trimmed = value.trim();
       if (this.editingCommentKey === GLOBAL_COMMENT_KEY) {
         if (!trimmed) {
@@ -210,13 +262,26 @@ export class ReviewComponent {
       return;
     }
 
+    if (this.askInputMode) {
+      if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+        this.exitAskInputMode();
+        return;
+      }
+      this.editor.handleInput(data);
+      this.invalidateAnnotatedRows();
+      this.tui.requestRender();
+      return;
+    }
+
     if (this.search.mode) {
       this.handleSearchInput(data);
       return;
     }
 
     if (matchesKey(data, "escape")) {
-      if (this.search.query) {
+      if (this.askScope) {
+        this.clearAsk();
+      } else if (this.search.query) {
         this.clearSearch();
       } else if (this.hasSelection()) {
         this.clearSelection();
@@ -226,7 +291,11 @@ export class ReviewComponent {
       return;
     }
     if (data === "q") {
-      this.done({ action: "cancel" });
+      if (this.hasSelection()) {
+        this.clearSelection();
+      } else {
+        this.done({ action: "cancel" });
+      }
       return;
     }
     if (data === "h") {
@@ -245,15 +314,19 @@ export class ReviewComponent {
       this.toggleExplanationPane();
       return;
     }
+    if (data === "a") {
+      this.startAskMode();
+      return;
+    }
     if (data === "/") {
       this.startSearchMode();
       return;
     }
-    if (matchesKey(data, "ctrl+d")) {
+    if (matchesKey(data, "pageDown") || matchesKey(data, "ctrl+d")) {
       this.move(this.getPageMoveAmount());
       return;
     }
-    if (matchesKey(data, "ctrl+u")) {
+    if (matchesKey(data, "pageUp") || matchesKey(data, "ctrl+u")) {
       this.move(-this.getPageMoveAmount());
       return;
     }
@@ -515,7 +588,9 @@ export class ReviewComponent {
         this.inlineAnnotationsVisible &&
       this.annotatedRowsVisibleExplanationCount ===
         this.visibleExplanationKeys.size &&
-      this.visibleExplanationKeys.size === 0
+      this.visibleExplanationKeys.size === 0 &&
+      !this.askInputMode &&
+      !this.askScope
     ) {
       return this.annotatedRows;
     }
@@ -659,30 +734,49 @@ export class ReviewComponent {
     width: number,
   ): void {
     const scope = getCurrentHunkScope(this.lines, lineIndex);
-    if (!scope || !this.visibleExplanationKeys.has(scope.key)) return;
+    if (!scope) return;
 
-    const end = this.getHunkEndIndex(lineIndex);
-    if (end !== lineIndex) return;
+    if (
+      this.visibleExplanationKeys.has(scope.key) &&
+      this.getExplanationAnchorIndex(lineIndex, scope.key) === lineIndex
+    ) {
+      const explanation = this.explanationController.getState(scope);
+      if (!this.explanationController.isAvailable) {
+        this.pushExplanationBlock(rows, "Explanation unavailable.", width);
+      } else if (!explanation) {
+        this.pushExplanationBlock(rows, "No explanation generated yet.", width);
+      } else if (explanation.status === "loading") {
+        this.pushExplanationBlock(
+          rows,
+          `${this.explanationController.getLoadingFrame()} ${explanation.text || "Generating explanation..."}`,
+          width,
+        );
+      } else if (explanation.status === "error") {
+        this.pushExplanationBlock(
+          rows,
+          `Explanation failed: ${explanation.message}`,
+          width,
+        );
+      } else {
+        this.pushExplanationBlock(rows, explanation.text, width);
+      }
+    }
 
-    const explanation = this.explanationController.getState(scope);
-    if (!this.explanationController.isAvailable) {
-      this.pushExplanationBlock(rows, "Explanation unavailable.", width);
-    } else if (!explanation) {
-      this.pushExplanationBlock(rows, "No explanation generated yet.", width);
-    } else if (explanation.status === "loading") {
-      this.pushExplanationBlock(
-        rows,
-        `${this.explanationController.getLoadingFrame()} ${explanation.text || "Generating explanation..."}`,
-        width,
-      );
-    } else if (explanation.status === "error") {
-      this.pushExplanationBlock(
-        rows,
-        `Explanation failed: ${explanation.message}`,
-        width,
-      );
-    } else {
-      this.pushExplanationBlock(rows, explanation.text, width);
+    if (
+      this.askInputMode &&
+      this.askScope?.key === scope.key &&
+      this.askAnchorIndex === lineIndex
+    ) {
+      this.pushInlineEditorBlock(rows, "Ask about this hunk", width);
+    }
+
+    if (
+      !this.askInputMode &&
+      this.askScope?.key === scope.key &&
+      this.askAnchorIndex === lineIndex
+    ) {
+      const askState = this.explanationController.getAskState();
+      if (askState) this.pushAskBlock(rows, askState, width);
     }
   }
 
@@ -717,14 +811,39 @@ export class ReviewComponent {
     rows.push({ kind: "comment", text: "", part: "bottom" });
   }
 
+  private pushAskBlock(
+    rows: AnnotatedDiffRow[],
+    state: ExplanationState,
+    width: number,
+  ): void {
+    if (state.status === "loading") {
+      this.pushExplanationBlock(
+        rows,
+        `${this.explanationController.getLoadingFrame()} ${state.text || "Generating answer..."}`,
+        width,
+        " 💬 Answer ",
+      );
+    } else if (state.status === "error") {
+      this.pushExplanationBlock(
+        rows,
+        `Failed: ${state.message}`,
+        width,
+        " 💬 Answer ",
+      );
+    } else {
+      this.pushExplanationBlock(rows, state.text, width, " 💬 Answer ");
+    }
+  }
+
   private pushExplanationBlock(
     rows: AnnotatedDiffRow[],
     text: string,
     width: number,
+    title = " ✨ Explanation ",
   ): void {
     rows.push({
       kind: "explanation",
-      text: this.theme.fg("accent", " ✨ Explanation "),
+      text: this.theme.fg("accent", title),
       part: "top",
     });
     const wrapped = wrapTextWithAnsi(
@@ -833,6 +952,27 @@ export class ReviewComponent {
     return comments.sort((a, b) => a.id.localeCompare(b.id));
   }
 
+  private restorePersistedAsk(
+    cachedAsk: PersistedAsk,
+  ): { scope: ExplanationScope; anchorIndex: number } | undefined {
+    const anchorIndex = this.lineIndexById.get(cachedAsk.anchorLineId);
+    if (anchorIndex != null) {
+      const scope = getCurrentHunkScope(this.lines, anchorIndex);
+      if (scope?.key === cachedAsk.scopeKey) {
+        return { scope, anchorIndex };
+      }
+    }
+
+    for (let index = 0; index < this.lines.length; index++) {
+      const scope = getCurrentHunkScope(this.lines, index);
+      if (scope?.key === cachedAsk.scopeKey) {
+        return { scope, anchorIndex: index };
+      }
+    }
+
+    return undefined;
+  }
+
   private getHunkEndIndex(selected: number): number | undefined {
     const selectedLine = this.lines[selected];
     if (!selectedLine?.filePath || !selectedLine.hunkLabel) return undefined;
@@ -848,6 +988,16 @@ export class ReviewComponent {
     return end;
   }
 
+  private getExplanationAnchorIndex(
+    lineIndex: number,
+    scopeKey: string,
+  ): number | undefined {
+    return (
+      this.explanationAnchorByScope.get(scopeKey) ??
+      this.getHunkEndIndex(lineIndex)
+    );
+  }
+
   private renderSplitDiffRowAt(splitRowIndex: number, width: number): string {
     const splitRow = this.getSplitDiffRows()[splitRowIndex];
     if (!splitRow) return " ".repeat(width);
@@ -891,6 +1041,41 @@ export class ReviewComponent {
 
   dispose(): void {
     this.explanationController.dispose();
+    this.clearAsk();
+  }
+
+  private startAskMode(): void {
+    const scope = this.getCurrentHunkScope();
+    if (!scope) return;
+    this.clearAsk();
+    this.askScope = scope;
+    this.askAnchorIndex = this.selected;
+    this.askInputMode = true;
+    this.inlineAnnotationsVisible = true;
+    this.editor.setText("");
+    this.invalidateAnnotatedRows();
+    this.tui.requestRender(true);
+  }
+
+  private exitAskInputMode(): void {
+    this.askInputMode = false;
+    this.editor.setText("");
+    if (!this.explanationController.getAskState()) {
+      this.askScope = undefined;
+      this.askAnchorIndex = undefined;
+    }
+    this.invalidateAnnotatedRows();
+    this.tui.requestRender(true);
+  }
+
+  private clearAsk(): void {
+    this.askInputMode = false;
+    this.askScope = undefined;
+    this.askAnchorIndex = undefined;
+    this.explanationController.clearAsk();
+    this.editor.setText("");
+    this.invalidateAnnotatedRows();
+    this.tui.requestRender(true);
   }
 
   private move(delta: number): void {
@@ -922,6 +1107,7 @@ export class ReviewComponent {
 
   private hideInlineExplanation(): void {
     this.visibleExplanationKeys.clear();
+    this.explanationAnchorByScope.clear();
   }
 
   private toggleExplanationPane(): void {
@@ -930,8 +1116,10 @@ export class ReviewComponent {
 
     if (this.visibleExplanationKeys.has(scope.key)) {
       this.visibleExplanationKeys.delete(scope.key);
+      this.explanationAnchorByScope.delete(scope.key);
     } else {
       this.visibleExplanationKeys.add(scope.key);
+      this.explanationAnchorByScope.set(scope.key, this.selected);
       this.ensureCurrentExplanation();
     }
 
@@ -1167,11 +1355,22 @@ export class ReviewComponent {
   private ensureScroll(viewportHeight: number, width: number): void {
     this.navigation.ensureScroll(
       viewportHeight,
-      this.getSelectedDisplayRow(width),
+      this.getScrollTargetDisplayRow(width),
       this.getDisplayRowCount(width),
     );
   }
 
+  private getScrollTargetDisplayRow(width: number): number {
+    if (this.editMode || this.askInputMode) {
+      const editorRow = this.getAnnotatedRows(width).findIndex(
+        (row) => row.kind === "editor",
+      );
+      if (editorRow >= 0) return editorRow;
+    }
+
+    return this.getSelectedDisplayRow(width);
+  }
+
   private getDisplayText(line: ReviewLine): string {
     const raw =
       line.kind === "add" || line.kind === "remove" || line.kind === "context"

package/src/review/types.ts

@@ -42,6 +42,12 @@ export type DiffSource = {
   args: string[];
 };
 
+export type PersistedAsk = {
+  scopeKey: string;
+  anchorLineId: string;
+  text: string;
+};
+
 export type DiffRenderMode = "unified" | "split";
 
 export type SplitDiffCell = {