pi-diff-review 0.1.18 → 0.1.20

package/README.md

@@ -49,6 +49,14 @@ Review a branch or commit range by passing any `git diff` arguments after `/diff
 
 `/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.
 
+Open one or more files or folders with `/view`:
+
+```text
+/view src/index.ts src/review
+```
+
+`/view` expands folders into text files, renders them in the same review UI, and lets you annotate actual code lines instead of diff hunks.
+
 ### Staged vs. unstaged changes
 
 - `/diff` shows unstaged working-tree changes only.
@@ -59,6 +67,7 @@ Review a branch or commit range by passing any `git diff` arguments after `/diff
 ## Features
 
 - `/diff` reviews the current unstaged `git diff`
+- `/view <files-or-folders>` reviews source files directly
 - `/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`
@@ -77,7 +86,9 @@ Review a branch or commit range by passing any `git diff` arguments after `/diff
 - `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
-- Comments are cached per session and restored when reopening the same diff
+- Comments are cached per session and restored when reopening the same diff or view
+- File comments are also persisted in a repo-local workspace store and shown again in `/view` or on matching lines in `/diff`
+- The UI indicates persisted comments that are hidden in the current files, elsewhere in the workspace, stale, or orphaned
 - `q` to exit
 
 ## Contributing

package/extensions/review.ts

@@ -1,6 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerDiffReviewCommand } from "../src/index.ts";
+import {
+  registerDiffReviewCommand,
+  registerViewCommand,
+} from "../src/index.ts";
 
 export default function (pi: ExtensionAPI) {
   registerDiffReviewCommand(pi);
+  registerViewCommand(pi);
 }

package/package.json

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

package/src/diff/source.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import type { DiffSource } from "../review/types.ts";
+import { tokenizeShellArgs } from "../shared/args.ts";
 
 export function parseDiffSource(args: string): DiffSource {
   const trimmed = args.trim();
@@ -20,48 +21,12 @@ export function parseDiffSource(args: string): DiffSource {
 }
 
 function tokenizeDiffArgs(input: string): string[] {
-  const args: string[] = [];
-  let current = "";
-  let quote: '"' | "'" | undefined;
-  let escaping = false;
-
-  for (const char of input) {
-    if (escaping) {
-      current += char;
-      escaping = false;
-      continue;
-    }
-
-    if (char === "\\" && quote !== "'") {
-      escaping = true;
-      continue;
-    }
-
-    if ((char === '"' || char === "'") && !quote) {
-      quote = char;
-      continue;
-    }
-
-    if (char === quote) {
-      quote = undefined;
-      continue;
-    }
-
-    if (/\s/.test(char) && !quote) {
-      if (current) {
-        args.push(current);
-        current = "";
-      }
-      continue;
-    }
-
-    current += char;
+  try {
+    return tokenizeShellArgs(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(message.replace(/in arguments$/, "in git diff args"));
   }
-
-  if (escaping) current += "\\";
-  if (quote) throw new Error(`Unterminated ${quote} quote in git diff args`);
-  if (current) args.push(current);
-  return args;
 }
 
 export const DIFF_MAX_BUFFER_BYTES = 128 * 1024 * 1024;

package/src/explanation/controller.ts

@@ -12,7 +12,40 @@ export function getCurrentHunkScope(
   selected: number,
 ): ExplanationScope | undefined {
   const selectedLine = lines[selected];
-  if (!selectedLine?.filePath || !selectedLine.hunkLabel) return undefined;
+  if (!selectedLine?.filePath) return undefined;
+  if (!selectedLine.commentable && !selectedLine.hunkLabel) return undefined;
+
+  if (!selectedLine.hunkLabel) {
+    let start = selected;
+    while (
+      start > 0 &&
+      lines[start - 1]?.filePath === selectedLine.filePath &&
+      lines[start - 1]?.commentable
+    ) {
+      start--;
+    }
+
+    let end = selected;
+    while (
+      end + 1 < lines.length &&
+      lines[end + 1]?.filePath === selectedLine.filePath &&
+      lines[end + 1]?.commentable
+    ) {
+      end++;
+    }
+
+    const diffText = lines
+      .slice(start, end + 1)
+      .map((line) => line.text.replace(/^ /, ""))
+      .join("\n");
+    return {
+      key: `file:${selectedLine.filePath}:${start}:${end}`,
+      kind: "file",
+      title: selectedLine.filePath,
+      filePath: selectedLine.filePath,
+      diffText,
+    };
+  }
 
   let start = selected;
   while (
@@ -62,12 +95,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 {
@@ -90,6 +130,7 @@ export class ExplanationController {
     const requestId = ++this.askRequestId;
     let text = "";
     this.askState = { status: "loading", text };
+    this.onAskChanged?.(this.askState);
     this.startLoadingTimer();
 
     void this.explainer
@@ -99,6 +140,7 @@ export class ExplanationController {
           if (requestId !== this.askRequestId) return;
           text += delta;
           this.askState = { status: "loading", text };
+          this.onAskChanged?.(this.askState);
           this.tui.requestRender();
         },
       })
@@ -108,6 +150,7 @@ export class ExplanationController {
           status: "ready",
           text: finalText.trim() || text.trim() || "No answer returned.",
         };
+        this.onAskChanged?.(this.askState);
       })
       .catch((error) => {
         if (requestId !== this.askRequestId) return;
@@ -116,6 +159,7 @@ export class ExplanationController {
           status: "error",
           message: error instanceof Error ? error.message : String(error),
         };
+        this.onAskChanged?.(this.askState);
       })
       .finally(() => {
         if (requestId !== this.askRequestId) return;
@@ -134,6 +178,7 @@ export class ExplanationController {
     this.askAbortController?.abort();
     this.askAbortController = undefined;
     this.askState = undefined;
+    this.onAskChanged?.(undefined);
   }
 
   ensure(scope: ExplanationScope | undefined): void {

package/src/explanation/explainer.ts

@@ -4,7 +4,7 @@ import type { AssistantMessage, Context } from "@earendil-works/pi-ai";
 
 export type ExplanationScope = {
   key: string;
-  kind: "hunk";
+  kind: "hunk" | "file";
   title: string;
   filePath?: string;
   diffText: string;
@@ -30,10 +30,30 @@ export function buildAskPrompt(
   scope: ExplanationScope,
   question: string,
 ): string {
+  if (scope.kind === "file") {
+    return `Given this code excerpt:\n\`\`\`${scope.filePath ? ` ${scope.filePath}` : ""}\n${scope.diffText}\n\`\`\`\n\n${question}`;
+  }
+
   return `Given this git diff hunk:\n\`\`\`diff\n${scope.diffText}\n\`\`\`\n\n${question}`;
 }
 
 export function buildExplanationPrompt(scope: ExplanationScope): string {
+  if (scope.kind === "file") {
+    return `Explain this code excerpt for a reviewer.
+
+Focus on:
+- what this code is doing
+- why it matters in context
+- behavioral, API, or test implications
+- notable risks or edge cases
+
+Keep it concise and practical.
+
+\`\`\`${scope.filePath ? ` ${scope.filePath}` : ""}
+${scope.diffText}
+\`\`\``;
+  }
+
   return `Explain this git diff hunk for a code reviewer.
 
 Focus on:
@@ -72,7 +92,7 @@ export class PiModelDiffExplainer implements DiffExplainer {
 
     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.",
+        "You explain code clearly and concisely for review. Focus on intent, behavior, and risk. Avoid restating every line.",
       messages: [
         {
           role: "user",

package/src/index.ts

@@ -6,139 +6,35 @@ import type {
 import { getDiff, parseDiffSource } from "./diff/source.ts";
 import { parseDiff } from "./diff/parser.ts";
 import { PiModelDiffExplainer } from "./explanation/explainer.ts";
-import { buildReviewPrompt } from "./review/prompt.ts";
+import {
+  getCachedAsk,
+  getCachedComments,
+  getCachedExplanations,
+  persistCachedAsk,
+  persistCachedComments,
+  persistCachedExplanations,
+} from "./review/cache.ts";
 import { ReviewComponent } from "./review/component.ts";
+import { buildReviewPrompt, buildViewReviewPrompt } from "./review/prompt.ts";
 import type {
-  DiffSource,
   ReviewComment,
+  ReviewLine,
   ReviewResult,
 } from "./review/types.ts";
+import { WorkspaceCommentStore } from "./review/workspace-comments.ts";
+import { parseViewFiles } from "./view/parser.ts";
+import { parseViewSource, resolveViewFiles } from "./view/source.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;
-  comments: ReviewComment[];
-  updatedAt: number;
-};
-
-type DiffExplanationCacheEntry = {
-  cacheKey: string;
-  explanations: Record<string, string>;
-  updatedAt: number;
-};
-
-function getDiffCacheKey(
-  cwd: string,
-  source: DiffSource,
-  diffText: string,
-): string {
-  const hash = createHash("sha256").update(diffText).digest("hex");
-  return `${cwd}\0${source.label}\0${hash}`;
-}
-
-function getCachedComments(
-  ctx: ExtensionCommandContext,
-  cacheKey: string,
-): Map<string, ReviewComment> {
-  let latest: DiffReviewCacheEntry | undefined;
-  for (const entry of ctx.sessionManager.getEntries()) {
-    if (
-      entry.type !== "custom" ||
-      entry.customType !== DIFF_REVIEW_CACHE_ENTRY
-    ) {
-      continue;
-    }
-
-    const data = entry.data as Partial<DiffReviewCacheEntry> | undefined;
-    if (data?.cacheKey !== cacheKey || !Array.isArray(data.comments)) {
-      continue;
-    }
-
-    if (!latest || (data.updatedAt ?? 0) >= latest.updatedAt) {
-      latest = {
-        cacheKey: data.cacheKey,
-        comments: data.comments,
-        updatedAt: data.updatedAt ?? 0,
-      };
-    }
-  }
-
-  return new Map(
-    (latest?.comments ?? []).map((comment) => [comment.id, comment]),
-  );
-}
-
-function persistCachedComments(
-  pi: ExtensionAPI,
-  cacheKey: string,
-  comments: Iterable<ReviewComment>,
-): void {
-  pi.appendEntry(DIFF_REVIEW_CACHE_ENTRY, {
-    cacheKey,
-    comments: [...comments],
-    updatedAt: Date.now(),
-  } 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);
+function getReviewCacheKey(cwd: string, label: string, text: string): string {
+  const hash = createHash("sha256").update(text).digest("hex");
+  return `${cwd}\0${label}\0${hash}`;
 }
 
 export function registerDiffReviewCommand(pi: ExtensionAPI): void {
   pi.registerCommand("diff", {
     description: "Review a git diff in a custom TUI (/diff [git diff args])",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
-      let source: DiffSource;
+      let source;
       let diffText: string;
       try {
         source = parseDiffSource(args);
@@ -155,54 +51,168 @@ 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",
-        );
+      await openReview(pi, ctx, {
+        title: source.label,
+        promptLabel: source.promptLabel,
+        cacheKey: getReviewCacheKey(ctx.cwd, source.label, diffText),
+        reviewLines,
+        buildPrompt: (comments) =>
+          buildReviewPrompt(comments, source.promptLabel),
+      });
+    },
+  });
+}
+
+export function registerViewCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("view", {
+    description:
+      "Review one or more files or folders in a custom TUI (/view <paths...>)",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      let source;
+      let files: string[];
+      try {
+        source = parseViewSource(args);
+        files = resolveViewFiles(ctx.cwd, source);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Unable to open view: ${message}`, "error");
+        return;
       }
-      if (explanations.size > 0) {
+
+      if (files.length === 0) {
         ctx.ui.notify(
-          `Restored ${explanations.size} cached hunk explanation${explanations.size === 1 ? "" : "s"}.`,
+          "No viewable text files matched the requested paths.",
           "info",
         );
+        return;
       }
 
-      const result = await ctx.ui.custom<ReviewResult>(
-        (tui, theme, _keybindings, done) => {
-          return new ReviewComponent(
-            tui,
-            theme,
-            source.label,
-            reviewLines,
-            comments,
-            done,
-            new PiModelDiffExplainer(ctx),
-            (updatedComments) => {
-              persistCachedComments(pi, cacheKey, updatedComments.values());
-            },
-            explanations,
-            (updatedExplanations) => {
-              persistCachedExplanations(pi, cacheKey, updatedExplanations);
-            },
+      const workspaceStore = new WorkspaceCommentStore(ctx.cwd);
+      const reviewLines = parseViewFiles(workspaceStore.rootPath, files);
+      const contentKey = reviewLines.map((line) => line.text).join("\n");
+
+      await openReview(pi, ctx, {
+        title: source.label,
+        promptLabel: source.promptLabel,
+        cacheKey: getReviewCacheKey(ctx.cwd, source.label, contentKey),
+        reviewLines,
+        workspaceStore,
+        buildPrompt: (comments) =>
+          buildViewReviewPrompt(comments, source.promptLabel),
+      });
+    },
+  });
+}
+
+async function openReview(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  options: {
+    title: string;
+    promptLabel: string;
+    cacheKey: string;
+    reviewLines: ReviewLine[];
+    buildPrompt: (comments: ReviewComment[]) => string;
+    workspaceStore?: WorkspaceCommentStore;
+  },
+): Promise<void> {
+  const workspaceStore =
+    options.workspaceStore ?? new WorkspaceCommentStore(ctx.cwd);
+  const cachedComments = getCachedComments(ctx, options.cacheKey);
+  const comments = workspaceStore.getVisibleComments(options.reviewLines);
+  for (const [id, comment] of cachedComments) {
+    comments.set(id, comment);
+  }
+
+  const explanations = getCachedExplanations(ctx, options.cacheKey);
+  const ask = getCachedAsk(ctx, options.cacheKey);
+  const summary = () => workspaceStore.summarize(options.reviewLines);
+
+  if (cachedComments.size > 0) {
+    ctx.ui.notify(
+      `Restored ${cachedComments.size} cached review comment${cachedComments.size === 1 ? "" : "s"}.`,
+      "info",
+    );
+  }
+  if (explanations.size > 0) {
+    ctx.ui.notify(
+      `Restored ${explanations.size} cached explanation${explanations.size === 1 ? "" : "s"}.`,
+      "info",
+    );
+  }
+  if (ask) {
+    ctx.ui.notify("Restored cached ask answer.", "info");
+  }
+
+  const initialSummary = summary();
+  if (initialSummary.hiddenInCurrentFiles > 0 || initialSummary.elsewhere > 0) {
+    ctx.ui.notify(
+      [
+        initialSummary.hiddenInCurrentFiles > 0
+          ? `${initialSummary.hiddenInCurrentFiles} comments hidden in current files`
+          : undefined,
+        initialSummary.elsewhere > 0
+          ? `${initialSummary.elsewhere} comments elsewhere in the workspace`
+          : undefined,
+      ]
+        .filter(Boolean)
+        .join(" • "),
+      "info",
+    );
+  }
+  if (initialSummary.stale > 0 || initialSummary.orphaned > 0) {
+    ctx.ui.notify(
+      [
+        initialSummary.stale > 0
+          ? `${initialSummary.stale} stale comment${initialSummary.stale === 1 ? "" : "s"}`
+          : undefined,
+        initialSummary.orphaned > 0
+          ? `${initialSummary.orphaned} orphaned comment${initialSummary.orphaned === 1 ? "" : "s"}`
+          : undefined,
+      ]
+        .filter(Boolean)
+        .join(" • "),
+      "warning",
+    );
+  }
+
+  const result = await ctx.ui.custom<ReviewResult>(
+    (tui, theme, _keybindings, done) => {
+      return new ReviewComponent(
+        tui,
+        theme,
+        options.title,
+        options.reviewLines,
+        comments,
+        done,
+        new PiModelDiffExplainer(ctx),
+        (updatedComments) => {
+          persistCachedComments(pi, options.cacheKey, updatedComments.values());
+          workspaceStore.syncFromComments(
+            options.reviewLines,
+            updatedComments.values(),
           );
         },
+        explanations,
+        (updatedExplanations) => {
+          persistCachedExplanations(pi, options.cacheKey, updatedExplanations);
+        },
+        ask,
+        (updatedAsk) => {
+          persistCachedAsk(pi, options.cacheKey, updatedAsk);
+        },
+        () => summary(),
       );
+    },
+  );
 
-      if (!result || result.action !== "submit") return;
-      if (result.comments.length === 0) {
-        ctx.ui.notify("No review comments to send.", "info");
-        persistCachedComments(pi, cacheKey, []);
-        return;
-      }
+  if (!result || result.action !== "submit") return;
+  if (result.comments.length === 0) {
+    ctx.ui.notify("No review comments to send.", "info");
+    persistCachedComments(pi, options.cacheKey, []);
+    return;
+  }
 
-      persistCachedComments(pi, cacheKey, []);
-      pi.sendUserMessage(
-        buildReviewPrompt(result.comments, source.promptLabel),
-      );
-    },
-  });
+  persistCachedComments(pi, options.cacheKey, []);
+  pi.sendUserMessage(options.buildPrompt(result.comments));
 }