sailfork / t3code-github / apps/ web/ src/ components/ chat/ citationProcedure.test.ts

import { MessageId, RunId } from "@t3tools/contracts";
import { describe, expect, it } from "vite-plus/test";
import type { TimelineEntry } from "../../session-logic";
import {
  type CitedThreadSnapshot,
  citedThreadSnapshot,
  loadCitedHistory,
  resolveCitationPhase,
} from "./citationProcedure";
import type { MessagesTimelineRow } from "./MessagesTimeline.logic";

function scriptedHistory(snapshots: ReadonlyArray<CitedThreadSnapshot | null>) {
  const controller = new AbortController();
  let reads = 0;
  let loads = 0;
  return {
    controller,
    get loads() {
      return loads;
    },
    run: (results: ReadonlyArray<"loaded" | "noop" | "error"> = []) =>
      loadCitedHistory({
        signal: controller.signal,
        readThread: async () => snapshots[Math.min(reads++, snapshots.length - 1)] ?? null,
        loadThrough: async () => {
          const result = results[loads++] ?? "loaded";
          return result === "error" ? { _tag: "error", message: "offline" } : { _tag: result };
        },
      }),
  };
}

const notLoaded = { message: null, hasMoreHistory: true } satisfies CitedThreadSnapshot;

describe("loadCitedHistory", () => {
  it("finds a cited response that is already loaded without paging", async () => {
    const history = scriptedHistory([{ message: "assistant", hasMoreHistory: true }]);
    await expect(history.run()).resolves.toEqual({ _tag: "found" });
    expect(history.loads).toBe(0);
  });

  it("pages history toward a response outside the loaded window", async () => {
    const history = scriptedHistory([
      notLoaded,
      notLoaded,
      { message: "assistant", hasMoreHistory: true },
    ]);
    await expect(history.run()).resolves.toEqual({ _tag: "found" });
    expect(history.loads).toBe(2);
  });

  it("reports an unavailable response once the thread has no more history", async () => {
    const history = scriptedHistory([notLoaded, { message: null, hasMoreHistory: false }]);
    await expect(history.run()).resolves.toMatchObject({
      _tag: "failed",
      title: "The cited response is unavailable",
    });
  });

  it("rejects a citation that names a user message", async () => {
    const history = scriptedHistory([{ message: "other", hasMoreHistory: false }]);
    await expect(history.run()).resolves.toMatchObject({
      _tag: "failed",
      title: "The citation does not refer to an assistant response",
    });
  });

  it("stops on a failed page", async () => {
    const history = scriptedHistory([notLoaded]);
    await expect(history.run(["error"])).resolves.toMatchObject({
      _tag: "failed",
      title: "Could not load the cited response",
    });
    expect(history.loads).toBe(1);
  });

  it("reports an unavailable response when the store has nothing older to page", async () => {
    const history = scriptedHistory([notLoaded]);
    await expect(history.run(["noop"])).resolves.toMatchObject({
      _tag: "failed",
      title: "The cited response is unavailable",
    });
    expect(history.loads).toBe(1);
  });

  it("gives up after a bounded number of pages that never reach the response", async () => {
    const history = scriptedHistory([notLoaded]);
    await expect(history.run()).resolves.toMatchObject({
      _tag: "failed",
      title: "Could not load the cited response",
    });
    expect(history.loads).toBe(20);
  });

  it("ends quietly when the citation is left mid-load", async () => {
    const history = scriptedHistory([notLoaded]);
    const outcome = history.run();
    history.controller.abort();
    await expect(outcome).resolves.toEqual({ _tag: "aborted" });
  });
});

describe("citedThreadSnapshot", () => {
  const settledHistory = {
    historyCursor: null,
    hasMoreHistory: false,
    loading: false,
    error: null,
    expanded: false,
    latestLocalTurnOrdinal: null,
  };
  const unloaded = {
    thread: null,
    history: settledHistory,
    status: "synchronizing",
    error: null,
    messageId: "cited",
  } satisfies Parameters<typeof citedThreadSnapshot>[0];

  it("keeps waiting while a thread that has not loaded yet is still synchronizing", () => {
    expect(citedThreadSnapshot(unloaded)).toBeNull();
  });

  it("fails the citation when the thread could not load at all", async () => {
    const snapshot = citedThreadSnapshot({ ...unloaded, error: "Thread not found." });
    expect(snapshot).not.toBeNull();
    await expect(scriptedHistory([snapshot]).run()).resolves.toMatchObject({
      _tag: "failed",
      title: "Could not load the cited response",
    });
  });
});

describe("resolveCitationPhase", () => {
  const at = "2026-01-01T00:00:00Z";
  const messageId = MessageId.make("cited");
  const runId = RunId.make("run-1");
  const entry: TimelineEntry = {
    kind: "message",
    id: "cited-entry",
    createdAt: at,
    message: {
      id: messageId,
      role: "assistant",
      text: "Answer",
      runId,
      streaming: false,
      createdAt: at,
      updatedAt: at,
    },
  };
  const row = {
    kind: "message",
    id: "cited-row",
    message: entry.message,
  } as MessagesTimelineRow;
  const phase = (input: {
    history?: "loading" | "found" | "failed";
    entries?: ReadonlyArray<TimelineEntry>;
    rows?: ReadonlyArray<MessagesTimelineRow>;
  }) =>
    resolveCitationPhase({
      history: { _tag: input.history ?? "loading" },
      messageId,
      entries: input.entries ?? [],
      rows: input.rows ?? [],
    });

  it("waits while the cited response is not in the timeline yet", () => {
    expect(phase({ history: "found" })).toEqual({ _tag: "loading" });
  });

  it("expands the turn that folds the cited response", () => {
    expect(phase({ entries: [entry] })).toEqual({ _tag: "expanding" });
  });

  it("is ready once the cited response has a row, even before paging settles", () => {
    expect(phase({ entries: [entry], rows: [row] })).toEqual({
      _tag: "ready",
      rowId: "cited-row",
    });
  });

  it("fails for a citation that names a user message", () => {
    const userEntry: TimelineEntry = {
      ...entry,
      message: { ...entry.message, role: "user" },
    } as TimelineEntry;
    expect(phase({ entries: [userEntry] })).toEqual({ _tag: "failed" });
  });

  it("fails when the history procedure failed", () => {
    expect(phase({ history: "failed", entries: [entry], rows: [row] })).toEqual({
      _tag: "failed",
    });
  });
});