@stigmer/react 3.1.3 → 3.1.5

package/src/workspace/__tests__/FileViewer.test.tsx

@@ -34,9 +34,10 @@ beforeEach(() => {
   };
 });
 import type { WorkspaceEntry } from "../useWorkspaceEntries";
-import type {
-  WorkspaceFileContent,
-  WorkspaceFileReader,
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileContent,
+  type WorkspaceFileReader,
 } from "../WorkspaceFileReader";
 
 function wholeFileChange(path: string): FileChange {
@@ -346,6 +347,140 @@ describe("FileViewer — diff mode", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Not-found fallback — captured content when the live substrate lacks the file
+// ---------------------------------------------------------------------------
+
+describe("FileViewer — not-found and captured-content fallback", () => {
+  function notFoundReader(): WorkspaceFileReader {
+    return vi.fn(async (_e, path: string) => {
+      throw new WorkspaceFileNotFoundError(path);
+    });
+  }
+
+  it("falls back to the captured after-content when the file isn't at the ref", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    // The captured after side ("beta") renders with the provenance caption —
+    // not an error, not the live caption.
+    await waitFor(() =>
+      expect(screen.getByText(/As of the agent.s last change/i)).toBeTruthy(),
+    );
+    expect(screen.getByText("beta")).toBeTruthy();
+    expect(screen.queryByText("Retry")).toBeNull();
+    expect(screen.queryByText(/Live — may differ/i)).toBeNull();
+  });
+
+  it("falls back to captured content when the substrate is unsupported (reader resolves null)", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={readerFor(null)}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() =>
+      expect(screen.getByText(/As of the agent.s last change/i)).toBeTruthy(),
+    );
+    expect(screen.getByText("beta")).toBeTruthy();
+  });
+
+  it("shows the calm not-found state (no error styling) when nothing is captured", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByText(/isn.t available in the workspace source yet/i)).toBeTruthy(),
+    );
+    // A calm notice, not a failure: retry is offered as "Check again".
+    expect(screen.getByText("Check again")).toBeTruthy();
+    expect(screen.queryByText("Retry")).toBeNull();
+  });
+
+  it("Check again re-reads and renders content once the file lands at the ref", async () => {
+    let attempt = 0;
+    const reader: WorkspaceFileReader = vi.fn(async (_e, path: string) => {
+      attempt += 1;
+      if (attempt === 1) throw new WorkspaceFileNotFoundError(path);
+      return text("now it exists");
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={reader}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByText("Check again")).toBeTruthy());
+    fireEvent.click(screen.getByText("Check again"));
+
+    await waitFor(() => expect(screen.getByText("now it exists")).toBeTruthy());
+  });
+
+  it("keeps the not-found state calm for a HUNK_ONLY change (no whole-file capture to serve)", async () => {
+    const hunkOnly = create(FileChangeSchema, {
+      path: "notes.md",
+      changeType: FileChangeType.MODIFY,
+      captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+      unifiedDiff: "@@ -1 +1 @@\n-alpha\n+beta\n",
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+        change={hunkOnly}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() =>
+      expect(screen.getByText(/isn.t available in the workspace source yet/i)).toBeTruthy(),
+    );
+    expect(screen.queryByText(/As of the agent.s last change/i)).toBeNull();
+  });
+
+  it("a generic reader error still shows the error state with Retry, never the fallback", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => {
+      throw new Error("rate limited (HTTP 429)");
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={reader}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() => expect(screen.getByText(/rate limited/i)).toBeTruthy());
+    expect(screen.getByText("Retry")).toBeTruthy();
+    expect(screen.queryByText(/As of the agent.s last change/i)).toBeNull();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Reveal (jump-to-line) — a line target opens File view and scrolls to it
 // ---------------------------------------------------------------------------

package/src/workspace/__tests__/useWorkspaceFileContent.test.tsx

@@ -172,6 +172,26 @@ describe("useWorkspaceFileContent", () => {
     expect(result.current.content?.text).toBe("FAST");
   });
 
+  it("re-reads when the entry's readRef advances (same id, new write-back push)", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async (e) =>
+      textContent(`at:${e.readRef ?? e.gitBranch}`),
+    );
+    const { result, rerender } = renderHook(
+      (props: { entry: WorkspaceEntry }) =>
+        useWorkspaceFileContent({ entry: props.entry, path: "notes.md", reader }),
+      { initialProps: { entry: gitEntry() } },
+    );
+
+    await waitFor(() => expect(result.current.content?.text).toBe("at:main"));
+
+    // A write-back push advances readRef while entry.id stays stable — the
+    // same path at a new ref is different content and must be re-read.
+    rerender({ entry: { ...gitEntry(), readRef: "sha-2" } });
+
+    await waitFor(() => expect(result.current.content?.text).toBe("at:sha-2"));
+    expect(reader).toHaveBeenCalledTimes(2);
+  });
+
   it("goes idle when the entry is removed (entry -> null)", async () => {
     const reader: WorkspaceFileReader = vi.fn(async () => textContent("x"));
     const { result, rerender } = renderHook(

package/src/workspace/__tests__/workspaceListingCache.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type { WorkspaceFileEntry, WorkspaceFileLister } from "../WorkspaceFileLister";
+import {
+  loadEntryFiles,
+  peekEntryListing,
+  __clearWorkspaceListingCache,
+} from "../workspaceListingCache";
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function listerFor(files: readonly WorkspaceFileEntry[]): WorkspaceFileLister {
+  return vi.fn(async () => [...files]);
+}
+
+describe("workspaceListingCache", () => {
+  beforeEach(() => {
+    __clearWorkspaceListingCache();
+  });
+
+  it("caches a listing and serves it without re-calling the lister", async () => {
+    const lister = listerFor([{ path: "a.ts", isDirectory: false }]);
+    const entry = gitEntry();
+
+    await loadEntryFiles(entry, lister);
+    await loadEntryFiles(entry, lister);
+
+    expect(lister).toHaveBeenCalledTimes(1);
+    expect(peekEntryListing(entry)?.files).toHaveLength(1);
+  });
+
+  it("treats a readRef advance as a different listing (stale-tree regression)", async () => {
+    // The write-back pushed a commit that added notes.md; the pre-push listing
+    // must not be served for the post-push ref.
+    const prePush = gitEntry(); // reads at gitBranch
+    const postPush = gitEntry({ readRef: "sha-after-push" });
+
+    const lister = vi.fn(async (entry: WorkspaceEntry) =>
+      entry.readRef
+        ? [
+            { path: "a.ts", isDirectory: false },
+            { path: "notes.md", isDirectory: false },
+          ]
+        : [{ path: "a.ts", isDirectory: false }],
+    );
+
+    const before = await loadEntryFiles(prePush, lister);
+    expect(before?.files.map((f) => f.path)).toEqual(["a.ts"]);
+
+    // Same entry.id, advanced ref — must re-fetch, not serve the stale tree.
+    const after = await loadEntryFiles(postPush, lister);
+    expect(lister).toHaveBeenCalledTimes(2);
+    expect(after?.files.map((f) => f.path)).toContain("notes.md");
+
+    // Both snapshots remain independently peekable at their own refs.
+    expect(peekEntryListing(prePush)?.files).toHaveLength(1);
+    expect(peekEntryListing(postPush)?.files).toHaveLength(2);
+  });
+
+  it("keys by entry id as well — two entries at the same ref never collide", async () => {
+    const one = gitEntry({ id: "ws-1" });
+    const two = gitEntry({ id: "ws-2", name: "acme/web", gitUrl: "https://github.com/acme/web" });
+
+    await loadEntryFiles(one, listerFor([{ path: "one.ts", isDirectory: false }]));
+    await loadEntryFiles(two, listerFor([{ path: "two.ts", isDirectory: false }]));
+
+    expect(peekEntryListing(one)?.files[0].path).toBe("one.ts");
+    expect(peekEntryListing(two)?.files[0].path).toBe("two.ts");
+  });
+
+  it("bustCache re-calls the lister for the same entry and ref", async () => {
+    const lister = listerFor([{ path: "a.ts", isDirectory: false }]);
+    const entry = gitEntry();
+
+    await loadEntryFiles(entry, lister);
+    await loadEntryFiles(entry, lister, { bustCache: true });
+
+    expect(lister).toHaveBeenCalledTimes(2);
+  });
+
+  it("never caches a null (unsupported) result", async () => {
+    const lister: WorkspaceFileLister = vi.fn(async () => null);
+    const entry = gitEntry();
+
+    expect(await loadEntryFiles(entry, lister)).toBeNull();
+    expect(peekEntryListing(entry)).toBeUndefined();
+
+    // A later, supporting lister must get its chance.
+    await loadEntryFiles(entry, listerFor([{ path: "a.ts", isDirectory: false }]));
+    expect(peekEntryListing(entry)?.files).toHaveLength(1);
+  });
+
+  it("collapses advisory notice entries into the truncated flag", async () => {
+    const lister = listerFor([
+      { path: "a.ts", isDirectory: false },
+      { path: "... (tree truncated)", isDirectory: false, notice: true },
+    ]);
+    const entry = gitEntry();
+
+    const listing = await loadEntryFiles(entry, lister);
+
+    expect(listing?.truncated).toBe(true);
+    expect(listing?.files.map((f) => f.path)).toEqual(["a.ts"]);
+  });
+});

package/src/workspace/index.ts

@@ -7,7 +7,10 @@ export type {
   WorkspaceFileEntry,
   WorkspaceFileLister,
 } from "./WorkspaceFileLister.js";
-export { MAX_WORKSPACE_FILE_READ_BYTES } from "./WorkspaceFileReader.js";
+export {
+  MAX_WORKSPACE_FILE_READ_BYTES,
+  WorkspaceFileNotFoundError,
+} from "./WorkspaceFileReader.js";
 export type {
   WorkspaceFileContent,
   WorkspaceFileReader,

package/src/workspace/useWorkspaceEntries.ts

@@ -33,6 +33,17 @@ export interface WorkspaceEntry {
   readonly gitUrl?: string;
   /** Branch to clone. Set when `type` is `"git"`. */
   readonly gitBranch?: string;
+  /**
+   * The git ref (branch or commit SHA) at which read-side operations —
+   * file content, tree listing, name search — resolve. Defaults to
+   * `gitBranch` when absent.
+   *
+   * Never user-configured: a session derives it from the latest workspace
+   * write-back so viewers read the agent's pushed commit instead of the
+   * stale base branch (see `useWorkspaceReadRefs`). A read-side projection
+   * only — never persisted, never part of the session input.
+   */
+  readonly readRef?: string;
   /** Absolute filesystem path. Set when `type` is `"local"`. */
   readonly localPath?: string;
 }

package/src/workspace/useWorkspaceFileContent.ts

@@ -105,7 +105,10 @@ export function useWorkspaceFileContent({
         ? () => reader(entry, path).then((c) => ({ content: c }))
         : null,
       // Identity deps: a change to any of these is a different file to read.
-      [entry?.id ?? null, path ?? null, reader],
+      // The read ref participates because the same path at a different ref is
+      // different content — a write-back push advances `readRef` while
+      // `entry.id` stays stable.
+      [entry?.id ?? null, entry?.readRef ?? null, path ?? null, reader],
       EMPTY_CONTENT,
     );
 

package/src/workspace/useWorkspaceFileSearch.ts

@@ -82,11 +82,16 @@ export function useWorkspaceFileSearch({
 }: UseWorkspaceFileSearchOptions): UseWorkspaceFileSearchReturn {
   const [states, setStates] = useState<Record<string, EntryListingState>>({});
 
-  // Latest entries read inside the effect without widening its dependency to the
-  // (possibly per-render) array identity — the effect keys on the id set instead.
+  // Latest entries read inside the effect without widening its dependency to
+  // the (possibly per-render) array identity — the effect keys on the set of
+  // (id, readRef) pairs instead. The ref participates because a listing is a
+  // snapshot of one ref: when a write-back advances an entry's readRef, its
+  // listing must be re-fetched even though the id set is unchanged.
   const entriesRef = useRef(entries);
   entriesRef.current = entries;
-  const entriesKey = entries.map((entry) => entry.id).join("\u0000");
+  const entriesKey = entries
+    .map((entry) => `${entry.id}\u0001${entry.readRef ?? ""}`)
+    .join("\u0000");
 
   // Ignore resolutions from a superseded entry set (id set or lister changed).
   const generationRef = useRef(0);

package/src/workspace/useWorkspaceFiles.ts

@@ -43,7 +43,8 @@ const EMPTY_TREE: readonly TreeNode[] = [];
  *   {@link loadEntryFiles} cache) when the
  *   entry changes.
  * - Reads the shared listing cache so tab switches, re-expands, and the search
- *   surface are instant without re-fetching (one cache, keyed by `entry.id`).
+ *   surface are instant without re-fetching (one cache, keyed by `entry.id` +
+ *   effective read ref — a ref advance is a cache miss by design).
  * - Returns an empty tree and skips the call when `lister` is
  *   `undefined` (graceful degradation — DD-011 opt-in).
  * - Memoizes the return value for referential stability (DD-010).
@@ -72,7 +73,7 @@ export function useWorkspaceFiles({
       if (!lister) return;
 
       if (!bustCache) {
-        const cached = peekEntryListing(target.id);
+        const cached = peekEntryListing(target);
         if (cached) {
           setTree(cached.tree);
           setTruncated(cached.truncated);

package/src/workspace/workspaceListingCache.ts

@@ -3,9 +3,12 @@
 // Both surfaces that need a listing read through here: the Files accordion
 // (`useWorkspaceFiles`, one entry) and workspace search (`useWorkspaceFileSearch`,
 // many entries). Keeping one module-level cache — keyed by the stable-within-page
-// `entry.id` — guarantees the two never double-fetch or drift, and lets one fetch
-// produce every shape a consumer needs (flat files for search, a tree for the
-// accordion, and the truncation flag for the banner).
+// `entry.id` plus the entry's effective read ref — guarantees the two never
+// double-fetch or drift, and lets one fetch produce every shape a consumer needs
+// (flat files for search, a tree for the accordion, and the truncation flag for
+// the banner). The ref is part of the key because a listing is a snapshot of one
+// ref: when a session's write-back advances `readRef`, the old listing is stale
+// by definition and must not be served.
 
 import { buildFileTree, type TreeNode } from "../internal/file-tree/index.js";
 import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
@@ -40,13 +43,24 @@ export interface LoadEntryFilesOptions {
 
 const sharedCache = new Map<string, WorkspaceListing>();
 
+/**
+ * Cache key for one entry's listing: identity plus the ref the listing was
+ * taken at. `entry.id` alone is NOT sufficient — it anchors file-selection
+ * identity across the surface and stays stable while `readRef` advances with
+ * each write-back push, so the ref must contribute to the key or consumers
+ * would see the pre-push tree forever.
+ */
+function listingCacheKey(entry: WorkspaceEntry): string {
+  return `${entry.id}\u0000${entry.readRef ?? entry.gitBranch ?? ""}`;
+}
+
 /**
  * Returns a cached {@link WorkspaceListing} for an entry synchronously, or
  * `undefined` when nothing is cached. Lets a consumer render a warm listing
  * instantly (no loading flash) before deciding whether to fetch.
  */
-export function peekEntryListing(entryId: string): WorkspaceListing | undefined {
-  return sharedCache.get(entryId);
+export function peekEntryListing(entry: WorkspaceEntry): WorkspaceListing | undefined {
+  return sharedCache.get(listingCacheKey(entry));
 }
 
 /**
@@ -63,7 +77,7 @@ export async function loadEntryFiles(
   options: LoadEntryFilesOptions = {},
 ): Promise<WorkspaceListing | null> {
   if (!options.bustCache) {
-    const cached = sharedCache.get(entry.id);
+    const cached = sharedCache.get(listingCacheKey(entry));
     if (cached) return cached;
   }
 
@@ -71,7 +85,7 @@ export async function loadEntryFiles(
   if (raw === null) return null;
 
   const listing = buildListing(raw);
-  sharedCache.set(entry.id, listing);
+  sharedCache.set(listingCacheKey(entry), listing);
   return listing;
 }