pi-diff-review 0.1.16 → 0.1.18

package/README.md

@@ -62,6 +62,7 @@ Review a branch or commit range by passing any `git diff` arguments after `/diff
 - `/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`
+- `h` toggles the command help modal
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-diff-review",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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>;
 
@@ -79,6 +82,60 @@ 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.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.tui.requestRender();
+        },
+      })
+      .then((finalText) => {
+        if (requestId !== this.askRequestId) return;
+        this.askState = {
+          status: "ready",
+          text: finalText.trim() || text.trim() || "No answer returned.",
+        };
+      })
+      .catch((error) => {
+        if (requestId !== this.askRequestId) return;
+        if (controller.signal.aborted) return;
+        this.askState = {
+          status: "error",
+          message: error instanceof Error ? error.message : String(error),
+        };
+      })
+      .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;
+  }
+
   ensure(scope: ExplanationScope | undefined): void {
     if (!scope || !this.explainer) return;
     if (this.explanations.has(scope.key)) return;
@@ -93,7 +150,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 +186,7 @@ export class ExplanationController {
 
   dispose(): void {
     this.abortController?.abort();
+    this.askAbortController?.abort();
     this.stopLoadingTimer();
   }
 
@@ -153,9 +211,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/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,
@@ -51,14 +55,38 @@ type AnnotatedDiffRow =
   | { kind: "split"; splitRowIndex: number }
   | InlineBoxRow;
 
+const HELP_COMMANDS = [
+  ["h", "show or hide this help"],
+  ["j/k or arrows", "move selection"],
+  ["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"],
+  ["/", "search diff lines"],
+  ["n / N", "jump between search matches"],
+  ["J / K", "extend highlighted selection"],
+  ["c", "add or edit a line or range comment"],
+  ["C", "add or edit an overall diff comment"],
+  ["x", "delete the current line or range comment"],
+  ["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"],
+] as const;
+
 export class ReviewComponent {
   private navigation: ReviewNavigationState;
   private editMode = false;
   private editingCommentKey?: string;
   private search: ReviewSearchState;
+  private helpVisible = false;
 
   private inlineAnnotationsVisible = true;
   private visibleExplanationKeys = new Set<string>();
+  private askInputMode = false;
+  private askScope?: ExplanationScope;
   private explanationController: ExplanationController;
   private editor: Editor;
   private splitRows?: SplitDiffRow[];
@@ -115,6 +143,19 @@ 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.invalidateAnnotatedRows();
+        this.tui.requestRender(true);
+        return;
+      }
       const trimmed = value.trim();
       if (this.editingCommentKey === GLOBAL_COMMENT_KEY) {
         if (!trimmed) {
@@ -171,6 +212,13 @@ export class ReviewComponent {
   }
 
   handleInput(data: string): void {
+    if (this.helpVisible) {
+      if (data === "h" || matchesKey(data, "escape")) {
+        this.toggleHelp();
+      }
+      return;
+    }
+
     if (this.editMode) {
       if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
         this.exitEditMode();
@@ -182,13 +230,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();
@@ -201,6 +262,10 @@ export class ReviewComponent {
       this.done({ action: "cancel" });
       return;
     }
+    if (data === "h") {
+      this.toggleHelp();
+      return;
+    }
     if (data === "t") {
       this.toggleInlineAnnotations();
       return;
@@ -213,6 +278,10 @@ export class ReviewComponent {
       this.toggleExplanationPane();
       return;
     }
+    if (data === "a") {
+      this.startAskMode();
+      return;
+    }
     if (data === "/") {
       this.startSearchMode();
       return;
@@ -292,15 +361,9 @@ export class ReviewComponent {
     const output: string[] = [];
 
     output.push(
-      truncateToWidth(
-        this.theme.fg(
-          "dim",
-          this.editMode
-            ? `${this.title} • ${this.lines.length} lines • ${this.comments.size} comments • editing inline comment • Enter save • Esc/Ctrl+C cancel`
-            : this.hasSelection()
-              ? `${this.title} • ${this.lines.length} lines • ${this.comments.size} comments • J/K extend • Esc clear selection • c comment range • C overall comment • Enter submit`
-              : `${this.title} • ${this.lines.length} lines • ${this.comments.size} comments • ${this.getPositionText(selectedLine)} • inline ${this.inlineAnnotationsVisible ? "shown" : "hidden"} • j/k move • g/G top/bottom • ctrl-u/d page • / search • t annotations • v unified/split • ? explain • J/K extend • c comment • C overall • x delete • ${this.search.query ? "n/N search" : "n/p hunk"} • Enter submit • q quit`,
-        ),
+      this.renderStatusLine(
+        this.getHeaderText(selectedLine),
+        "Press h for help",
         width,
       ),
     );
@@ -314,9 +377,132 @@ export class ReviewComponent {
         width,
       ),
     );
+    return this.helpVisible ? this.renderHelpModal(output, width) : output;
+  }
+
+  private getHeaderText(selectedLine?: ReviewLine): string {
+    const base = `${this.title} • ${this.lines.length} lines • ${this.comments.size} comments`;
+
+    if (this.editMode) {
+      return `${base} • editing ${this.editingCommentKey === GLOBAL_COMMENT_KEY ? "overall comment" : "inline comment"}`;
+    }
+
+    if (this.hasSelection()) {
+      return `${base} • selection active`;
+    }
+
+    return `${base} • ${this.getPositionText(selectedLine)} • inline ${this.inlineAnnotationsVisible ? "shown" : "hidden"} • ${this.diffRenderMode}`;
+  }
+
+  private renderStatusLine(left: string, right: string, width: number): string {
+    const styledLeft = this.theme.fg("dim", left);
+    const styledRight = this.theme.fg("muted", right);
+    const rightWidth = visibleWidth(styledRight);
+    const leftWidth = Math.max(0, width - rightWidth - 1);
+    const truncatedLeft = truncateToWidth(styledLeft, leftWidth);
+    const spacer = Math.max(
+      1,
+      width - visibleWidth(truncatedLeft) - rightWidth,
+    );
+    return truncateToWidth(
+      `${truncatedLeft}${" ".repeat(spacer)}${styledRight}`,
+      width,
+    );
+  }
+
+  private renderHelpModal(rows: string[], width: number): string[] {
+    if (rows.length === 0 || width < 8) return rows;
+
+    const modalWidth = Math.max(8, Math.min(72, width - 2));
+    const contentWidth = Math.max(4, modalWidth - 4);
+    const keyWidth = Math.min(16, Math.max(8, Math.floor(contentWidth * 0.35)));
+    const modalRows = this.buildHelpModalRows(
+      modalWidth,
+      contentWidth,
+      keyWidth,
+    );
+    const maxRows = Math.max(1, rows.length - 2);
+    const visibleModalRows =
+      modalRows.length > maxRows
+        ? [
+            ...modalRows.slice(0, maxRows - 1),
+            this.renderModalRow(
+              this.theme.fg("dim", "More commands available on taller screens"),
+              contentWidth,
+            ),
+          ]
+        : modalRows;
+    const top = Math.max(
+      1,
+      Math.floor((rows.length - visibleModalRows.length) / 2),
+    );
+    const left = Math.max(0, Math.floor((width - modalWidth) / 2));
+
+    const output = [...rows];
+    for (let index = 0; index < visibleModalRows.length; index++) {
+      const row = visibleModalRows[index]!;
+      output[top + index] = padToWidth(
+        truncateToWidth(`${" ".repeat(left)}${row}`, width),
+        width,
+      );
+    }
     return output;
   }
 
+  private buildHelpModalRows(
+    modalWidth: number,
+    contentWidth: number,
+    keyWidth: number,
+  ): string[] {
+    const rows = [
+      this.renderModalHorizontal(" Help ", modalWidth, "top"),
+      this.renderModalRow(
+        this.theme.fg("dim", "Press h or Esc to close."),
+        contentWidth,
+      ),
+      this.renderModalRow("", contentWidth),
+    ];
+
+    for (const [keys, description] of HELP_COMMANDS) {
+      const keyCell = padToWidth(
+        truncateToWidth(this.theme.fg("accent", keys), keyWidth),
+        keyWidth,
+      );
+      rows.push(
+        this.renderModalRow(
+          `${keyCell} ${this.theme.fg("text", description)}`,
+          contentWidth,
+        ),
+      );
+    }
+
+    rows.push(this.renderModalHorizontal("", modalWidth, "bottom"));
+    return rows;
+  }
+
+  private renderModalRow(text: string, contentWidth: number): string {
+    return `${this.theme.fg("borderMuted", "│")} ${padToWidth(
+      truncateToWidth(text, contentWidth),
+      contentWidth,
+    )} ${this.theme.fg("borderMuted", "│")}`;
+  }
+
+  private renderModalHorizontal(
+    title: string,
+    width: number,
+    part: "top" | "bottom",
+  ): string {
+    const contentWidth = Math.max(0, width - 2);
+    const visibleTitle = truncateToWidth(title, contentWidth);
+    const remaining = Math.max(0, contentWidth - visibleWidth(visibleTitle));
+    const left = part === "top" ? "╭" : "╰";
+    const right = part === "top" ? "╮" : "╯";
+    return `${this.theme.fg("borderMuted", left)}${visibleTitle}${this.theme.fg(
+      "borderMuted",
+      "─".repeat(remaining),
+    )}${this.theme.fg("borderMuted", right)}`;
+  }
+
   private renderAnnotatedDiffRows(width: number, height: number): string[] {
     const rows = this.getAnnotatedRows(width);
     const output: string[] = [];
@@ -366,7 +552,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;
     }
@@ -510,30 +698,41 @@ 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;
 
-    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.visibleExplanationKeys.has(scope.key)) {
+      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.pushInlineEditorBlock(rows, "Ask about this hunk", width);
+    }
+
+    if (!this.askInputMode && this.askScope?.key === scope.key) {
+      const askState = this.explanationController.getAskState();
+      if (askState) this.pushAskBlock(rows, askState, width);
     }
   }
 
@@ -568,14 +767,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(
@@ -742,6 +966,36 @@ 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.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.invalidateAnnotatedRows();
+    this.tui.requestRender(true);
+  }
+
+  private clearAsk(): void {
+    this.askInputMode = false;
+    this.askScope = undefined;
+    this.explanationController.clearAsk();
+    this.editor.setText("");
+    this.invalidateAnnotatedRows();
+    this.tui.requestRender(true);
   }
 
   private move(delta: number): void {
@@ -766,6 +1020,11 @@ export class ReviewComponent {
     this.tui.requestRender(true);
   }
 
+  private toggleHelp(): void {
+    this.helpVisible = !this.helpVisible;
+    this.tui.requestRender(true);
+  }
+
   private hideInlineExplanation(): void {
     this.visibleExplanationKeys.clear();
   }
@@ -1013,11 +1272,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"