Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

18.0 KB
Raw Blame
/**
 * The Files panel's logic (lib/workspace-tree.ts).
 *
 * - A path names its parent and the directories above it; expanding to a file opens the way
 *   down without treating the file as a directory, and collapsing closes only that directory.
 * - Listings sort directories before files by name; an entry upserts into sorted position,
 *   replacing a same-named one, starting a listing where there was none, never mutating.
 * - The tree's rows walk open directories depth first, number each row within its directory,
 *   and mark an open directory still loading or empty; a whole-Workspace search draws a flat
 *   list of hits named by their whole path, carrying size and time.
 * - A drop lands on a folder row, in a file row's directory, or in the current directory.
 * - Below the width threshold the panel is one column (two panes while unmeasured); an
 *   undragged tree takes about a third within readable bounds, and a dragged width is clamped.
 * - A file's kind comes from its name, or from its bytes when the name says nothing (UTF-8 text
 *   cut mid-character is still text; NUL, control-heavy or non-UTF-8 bytes are not); the
 *   read-only browser reads HTML as source and an unknown name as unsupported; only whole
 *   text-like previews offer the editor, and leaving typed changes asks first.
 * - The tree width, soft wrap and tree visibility preferences parse tolerantly, keep a stored
 *   explicit answer over a new default, round-trip, and fall back when storage throws.
 * - A line range is written as an editor writes it; a directory reference carries a trailing
 *   slash.
 * - "Add to conversation" hands the composer a reference (the text it will send and its file),
 *   still fenced as a quotation, never text for the draft.
 */
import { describe, expect, it } from "vitest";
import type { WorkspaceFileEntry, WorkspaceSearchHit } from "@adelie/server/api";
import { blockedStorage, memoryStorage } from "./helpers/storage";
import {
  type ComposerReference,
  type Listings,
  PREVIEW_MIN_WIDTH,
  TREE_LAYOUT_MIN_WIDTH,
  TREE_MIN_WIDTH,
  ancestorDirs,
  canEditPreview,
  clampTreeWidth,
  defaultTreeWidth,
  dropTargetDir,
  expandTo,
  searchRows,
  flattenTree,
  isDirty,
  isNarrowLayout,
  looksLikeText,
  maxTreeWidth,
  needsDiscardConfirm,
  parentDir,
  parseWrapLines,
  parseTreeVisible,
  parseTreeWidth,
  pathReference,
  previewKindFor,
  previewKindOf,
  readWrapLines,
  readTreeVisible,
  readTreeWidth,
  selectionBlock,
  lineSuffix,
  sortEntries,
  upsertEntry,
  utf8Complete,
  withExpanded,
  writeWrapLines,
  writeTreeVisible,
  writeTreeWidth,
} from "../src/lib/workspace-tree";

const MTIME = "2026-09-02T00:00:00.000Z";
const dir = (name: string): WorkspaceFileEntry => ({
  name,
  kind: "dir",
  sizeBytes: 0,
  mtime: MTIME,
});
const file = (name: string, sizeBytes = 1): WorkspaceFileEntry => ({
  name,
  kind: "file",
  sizeBytes,
  mtime: MTIME,
});

/** root: a/ (b/ empty, y.md), x.txt — the shape every tree test walks. */
const LISTINGS: Listings = new Map([
  ["", [dir("a"), file("x.txt")]],
  ["a", [dir("b"), file("y.md")]],
  ["a/b", []],
]);

describe("paths", () => {
  it("names a path's parent and the directories above it, root first", () => {
    expect(parentDir("x.txt")).toBe("");
    expect(parentDir("a/b/c.txt")).toBe("a/b");
    expect(ancestorDirs("x.txt")).toEqual([""]);
    expect(ancestorDirs("a/b/c.txt")).toEqual(["", "a", "a/b"]);
  });

  it("expandTo opens the way down to a file without opening the file's own name as a directory", () => {
    expect([...expandTo(new Set(), "a/b/c.txt")].sort()).toEqual(["", "a", "a/b"]);
  });

  it("withExpanded opens a directory with its ancestors and closes only the directory itself", () => {
    const opened = withExpanded(new Set(), "a/b", true);
    expect(opened.has("a")).toBe(true);
    expect(opened.has("a/b")).toBe(true);
    // Closing "a" leaves "a/b" recorded, so reopening "a" shows the subtree as it was left.
    const closed = withExpanded(opened, "a", false);
    expect(closed.has("a")).toBe(false);
    expect(closed.has("a/b")).toBe(true);
  });
});

describe("listings", () => {
  it("sorts directories before files, each group by name", () => {
    expect(
      sortEntries([file("z.txt"), dir("m"), file("a.txt"), dir("b")]).map((e) => e.name),
    ).toEqual(["b", "m", "a.txt", "z.txt"]);
  });

  it("upsertEntry inserts in sorted position, replaces a same-named entry, and leaves the input alone", () => {
    const withFile = upsertEntry(LISTINGS, "", file("m.txt"));
    expect(withFile.get("")!.map((e) => e.name)).toEqual(["a", "m.txt", "x.txt"]);
    const withDir = upsertEntry(withFile, "", dir("z"));
    expect(withDir.get("")!.map((e) => e.name)).toEqual(["a", "z", "m.txt", "x.txt"]);
    const replaced = upsertEntry(withDir, "", file("x.txt", 99));
    expect(replaced.get("")!.filter((e) => e.name === "x.txt")).toEqual([file("x.txt", 99)]);
    expect(LISTINGS.get("")!.map((e) => e.name)).toEqual(["a", "x.txt"]);
  });

  it("upsertEntry into a directory with no listing yet starts one", () => {
    expect(upsertEntry(LISTINGS, "new", file("n.txt")).get("new")).toEqual([file("n.txt")]);
  });
});

describe("flattenTree", () => {
  it("walks open directories depth-first and skips closed ones", () => {
    const rows = flattenTree(LISTINGS, new Set(["a", "a/b"]));
    expect(rows.map((r) => [r.path, r.depth])).toEqual([
      ["a", 0],
      ["a/b", 1],
      ["a/y.md", 1],
      ["x.txt", 0],
    ]);
    expect(flattenTree(LISTINGS, new Set()).map((r) => r.path)).toEqual(["a", "x.txt"]);
  });

  it("numbers each row within its own directory, so a flat tree can state its set", () => {
    const rows = flattenTree(LISTINGS, new Set(["a"]));
    expect(rows.map((r) => [r.path, r.posInSet, r.setSize])).toEqual([
      ["a", 1, 2],
      ["a/b", 1, 2],
      ["a/y.md", 2, 2],
      ["x.txt", 2, 2],
    ]);
  });

  it("marks an open directory that is still loading, and an open one that is empty", () => {
    const loading = flattenTree(new Map([["", [dir("a")]]]), new Set(["a"]));
    expect(loading).toHaveLength(1);
    expect(loading[0]).toMatchObject({ path: "a", expanded: true, loaded: false, empty: false });
    const rows = flattenTree(LISTINGS, new Set(["a", "a/b"]));
    expect(rows.find((r) => r.path === "a/b")).toMatchObject({ loaded: true, empty: true });
    expect(rows.find((r) => r.path === "a")).toMatchObject({ loaded: true, empty: false });
  });
});

describe("dropTargetDir", () => {
  it("lands on a folder row, in a file row's directory, or in the current directory", () => {
    expect(dropTargetDir({ kind: "dir", path: "docs/api" }, "src")).toBe("docs/api");
    expect(dropTargetDir({ kind: "file", path: "docs/api/README.md" }, "src")).toBe("docs/api");
    expect(dropTargetDir({ kind: "file", path: "top.txt" }, "src")).toBe("");
    expect(dropTargetDir(null, "src")).toBe("src");
  });
});

describe("layout", () => {
  it("falls back to one column below the threshold and keeps two panes while unmeasured", () => {
    expect(isNarrowLayout(0)).toBe(false);
    expect(isNarrowLayout(TREE_LAYOUT_MIN_WIDTH - 1)).toBe(true);
    expect(isNarrowLayout(TREE_LAYOUT_MIN_WIDTH)).toBe(false);
  });

  it("gives an undragged tree about a third of the panel within readable bounds", () => {
    expect(defaultTreeWidth(480)).toBe(173);
    expect(defaultTreeWidth(320)).toBe(168);
    expect(defaultTreeWidth(1200)).toBe(256);
  });

  it("clamps a dragged width to the tree's minimum and the preview's room", () => {
    expect(clampTreeWidth(300, 1000)).toBe(300);
    expect(clampTreeWidth(40, 1000)).toBe(TREE_MIN_WIDTH);
    expect(clampTreeWidth(900, 1000)).toBe(1000 - PREVIEW_MIN_WIDTH);
    // A panel with no room for both still has bounds, just no range between them.
    expect(maxTreeWidth(300)).toBe(TREE_MIN_WIDTH);
    expect(clampTreeWidth(300, 300)).toBe(TREE_MIN_WIDTH);
    // Unmeasured (0, before the first ResizeObserver callback): no ceiling to apply yet.
    expect(clampTreeWidth(400, 0)).toBe(400);
    expect(clampTreeWidth(Number.NaN, 1000)).toBe(TREE_MIN_WIDTH);
  });
});

describe("searchRows", () => {
  const hits: WorkspaceSearchHit[] = [
    { path: "notes.md", kind: "file", sizeBytes: 12, mtime: "2026-09-11T00:00:00.000Z" },
    { path: "a/deep", kind: "dir", sizeBytes: 0, mtime: "2026-09-11T00:00:01.000Z" },
    { path: "a/deep/notes.md", kind: "file", sizeBytes: 34, mtime: "2026-09-11T00:00:02.000Z" },
  ];

  it("names each hit by its whole path, because where it is is the part the query did not say", () => {
    // The base name is what the reader just typed; two hits called notes.md are told apart
    // only by the directory in front of them.
    expect(searchRows(hits).map((r) => r.name)).toEqual(["notes.md", "a/deep", "a/deep/notes.md"]);
    expect(searchRows(hits).map((r) => r.path)).toEqual(["notes.md", "a/deep", "a/deep/notes.md"]);
  });

  it("draws a flat list, not a tree: every row is depth 0 and closed", () => {
    // A hit can live in a directory the lazy tree never listed, so there is nothing to nest it
    // under; an open directory row here would promise children the panel cannot draw.
    const rows = searchRows(hits);
    expect(rows.every((r) => r.depth === 0)).toBe(true);
    expect(rows.every((r) => !r.expanded)).toBe(true);
    expect(rows.map((r) => r.posInSet)).toEqual([1, 2, 3]);
    expect(rows.every((r) => r.setSize === 3)).toBe(true);
  });

  it("carries the size and time the row renderer shows, so a hit reads like a tree entry", () => {
    expect(searchRows(hits).map((r) => r.sizeBytes)).toEqual([12, 0, 34]);
    expect(searchRows(hits)[2]?.mtime).toBe("2026-09-11T00:00:02.000Z");
    expect(searchRows([])).toEqual([]);
  });
});

describe("file kinds", () => {
  it("decides the preview kind from the name, leaving an unknown name to be sniffed", () => {
    expect(previewKindFor("README.md")).toBe("md");
    expect(previewKindFor("index.HTML")).toBe("html");
    expect(previewKindFor(".gitignore")).toBe("text");
    expect(previewKindFor("photo.PNG")).toBe("image");
    expect(previewKindFor("paper.pdf")).toBe("pdf");
    // Word previews through the server's text extraction, in both the modern and the legacy
    // extension: the panel tells them apart when it loads one (a .doc gets its own message).
    expect(previewKindFor("设计稿.docx")).toBe("doc");
    expect(previewKindFor("old.DOC")).toBe("doc");
    expect(previewKindFor("Makefile")).toBe("unknown");
    expect(previewKindFor("archive.tar.gz")).toBe("unknown");
  });

  it("reads HTML as source and an unknown name as unsupported in the read-only browser", () => {
    expect(previewKindOf("index.html")).toBe("text");
    expect(previewKindOf("Makefile")).toBe("unsupported");
    expect(previewKindOf("README.md")).toBe("md");
    // No extraction fetch in the read-only browser: a Word file reads as unsupported there.
    expect(previewKindOf("设计稿.docx")).toBe("unsupported");
  });

  it("takes UTF-8 text for text, including a chunk cut inside a multi-byte character", () => {
    const encode = (s: string) => new TextEncoder().encode(s);
    expect(looksLikeText(encode("all: build\n\tgo build ./...\n"))).toBe(true);
    expect(looksLikeText(encode("ok 世界\n"))).toBe(true);
    // "世界" is six bytes; four of them end mid-character, which is a boundary, not binary.
    expect(looksLikeText(encode("世界").subarray(0, 4))).toBe(true);
    expect(utf8Complete(encode("世界").subarray(0, 4))).toEqual(encode("世"));
    expect(looksLikeText(new Uint8Array())).toBe(true);
  });

  it("rejects a NUL byte, a control-heavy sample, and bytes that are not UTF-8", () => {
    expect(
      looksLikeText(Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0])),
    ).toBe(false);
    expect(looksLikeText(Uint8Array.from([1, 2, 3, 4, 5, 0x41]))).toBe(false);
    // "café" in Latin-1: the lone 0xE9 followed by ASCII is not a UTF-8 sequence.
    expect(looksLikeText(Uint8Array.from([0x63, 0x61, 0x66, 0xe9, 0x20, 0x61]))).toBe(false);
  });
});

describe("editing", () => {
  it("offers the editor for whole text-like previews only", () => {
    expect(canEditPreview({ kind: "text" })).toBe(true);
    expect(canEditPreview({ kind: "md", truncated: false })).toBe(true);
    expect(canEditPreview({ kind: "html" })).toBe(true);
    // A truncated read must stay read-only: saving it would write the cut text over the file.
    expect(canEditPreview({ kind: "text", truncated: true })).toBe(false);
    expect(canEditPreview({ kind: "image" })).toBe(false);
    expect(canEditPreview({ kind: "unsupported" })).toBe(false);
  });

  it("asks before leaving typed changes, not for a clean editor or the file being edited", () => {
    const version = 'W/"1-1000"';
    const clean = { path: "a.txt", baseline: "x", draft: "x", version };
    const dirty = { path: "a.txt", baseline: "x", draft: "xy", version };
    expect(isDirty(null)).toBe(false);
    expect(isDirty(clean)).toBe(false);
    expect(isDirty(dirty)).toBe(true);
    expect(needsDiscardConfirm(null, "b.txt")).toBe(false);
    expect(needsDiscardConfirm(clean, "b.txt")).toBe(false);
    expect(needsDiscardConfirm(dirty, "b.txt")).toBe(true);
    expect(needsDiscardConfirm(dirty, null)).toBe(true);
    expect(needsDiscardConfirm(dirty, "a.txt")).toBe(false);
  });
});

describe("tree width preference", () => {
  it("takes a positive integer and treats everything else as unset", () => {
    expect(parseTreeWidth(null)).toBeNull();
    expect(parseTreeWidth(" 220 ")).toBe(220);
    expect(parseTreeWidth("240px")).toBe(240);
    expect(parseTreeWidth("garbage")).toBeNull();
    expect(parseTreeWidth("0")).toBeNull();
    expect(parseTreeWidth("-40")).toBeNull();
  });

  it("round-trips through storage and reads as unset when storage throws", () => {
    const storage = memoryStorage();
    expect(readTreeWidth(storage)).toBeNull();
    writeTreeWidth(233.4, storage);
    expect(readTreeWidth(storage)).toBe(233);
    expect(readTreeWidth(blockedStorage())).toBeNull();
    expect(() => writeTreeWidth(200, blockedStorage())).not.toThrow();
  });
});

describe("soft wrap preference", () => {
  it("wraps unless an explicit off value is stored, so a stored answer survives the new default", () => {
    expect(parseWrapLines(null)).toBe(true);
    expect(parseWrapLines("garbage")).toBe(true);
    expect(parseWrapLines("1")).toBe(true);
    expect(parseWrapLines("0")).toBe(false);
    expect(parseWrapLines(" FALSE ")).toBe(false);
  });

  it("round-trips through storage and reads as on when storage throws", () => {
    const storage = memoryStorage();
    expect(readWrapLines(storage)).toBe(true);
    writeWrapLines(false, storage);
    expect(readWrapLines(storage)).toBe(false);
    writeWrapLines(true, storage);
    expect(readWrapLines(storage)).toBe(true);
    expect(readWrapLines(blockedStorage())).toBe(true);
    expect(() => writeWrapLines(false, blockedStorage())).not.toThrow();
  });
});

describe("tree visibility preference", () => {
  it("shows the tree unless an explicit off value is stored", () => {
    expect(parseTreeVisible(null)).toBe(true);
    expect(parseTreeVisible("1")).toBe(true);
    expect(parseTreeVisible("garbage")).toBe(true);
    expect(parseTreeVisible("0")).toBe(false);
    expect(parseTreeVisible(" FALSE ")).toBe(false);
  });

  it("round-trips through storage and defaults to shown when storage throws", () => {
    const storage = memoryStorage();
    expect(readTreeVisible(storage)).toBe(true);
    writeTreeVisible(false, storage);
    expect(readTreeVisible(storage)).toBe(false);
    writeTreeVisible(true, storage);
    expect(readTreeVisible(storage)).toBe(true);
    expect(readTreeVisible(blockedStorage())).toBe(true);
    expect(() => writeTreeVisible(false, blockedStorage())).not.toThrow();
  });
});

describe("lineSuffix", () => {
  it("writes a range the way an editor and a stack trace do", () => {
    expect(lineSuffix(12, 18)).toBe(":12-18");
    expect(lineSuffix(7, 7)).toBe(":7");
  });
});

describe("composer references", () => {
  it("marks a directory with a trailing slash and leaves a file bare", () => {
    expect(pathReference("src/lib/tree.ts", "file")).toBe("@src/lib/tree.ts");
    expect(pathReference("src/lib", "dir")).toBe("@src/lib/");
  });
});

describe("what the panel hands the composer is a reference, not text for the draft", () => {
  const block = selectionBlock({
    path: "src/app.ts",
    language: "ts",
    selection: "const x = 1;",
    fromLine: 3,
    toLine: 3,
  });

  it("carries the text it will send and the file it came from", () => {
    // The chip shows the path; the block is what the message carries. Keeping the two on one
    // object is what lets the composer show one and send the other.
    const reference: ComposerReference = {
      kind: "quote",
      path: "src/app.ts",
      text: block,
      fromLine: 3,
      toLine: 3,
    };
    expect(reference.text).toContain("@src/app.ts:3");
    expect(reference.text).toContain("const x = 1;");
    expect(reference.path).toBe("src/app.ts");
  });

  it("still fences the quotation, so the composer could not have shown it as a line of the draft", () => {
    // The reason this is a chip at all: what it carries is a multi-line block, and splicing a
    // block into a half-typed sentence buries the sentence.
    expect(block.split("\n").length).toBeGreaterThan(2);
    expect(block).toMatch(/```/);
  });

  it("carries a file and a directory the same way, each naming its own kind", () => {
    // All three kinds go through one channel, so the composer has one chip to draw and the
    // panel has no second path that could put text in the draft again.
    const file: ComposerReference = {
      kind: "file",
      path: "src/app.ts",
      text: pathReference("src/app.ts", "file"),
    };
    const dir: ComposerReference = {
      kind: "dir",
      path: "src/lib",
      text: pathReference("src/lib", "dir"),
    };
    expect(file.text).toBe("@src/app.ts");
    expect(dir.text).toBe("@src/lib/");
    expect([file.kind, dir.kind]).toEqual(["file", "dir"]);
    // Neither carries a line range: a whole entry has no lines to name.
    expect(file.fromLine).toBeUndefined();
    expect(dir.fromLine).toBeUndefined();
  });
});