@vellumai/assistant 0.8.5 → 0.8.7

package/src/memory/v3/__tests__/traversal.test.ts

@@ -1,469 +0,0 @@
-/**
- * Tests for `assistant/src/memory/v3/traversal.ts`.
- *
- * Provider-free: `descend` is always a deterministic stub. Coverage:
- *   - resolveChildren is a thin accessor (known node / leaf / unknown id).
- *   - linear descent collects the expected leaf pages and emits a TreeLevel per
- *     walked node in walk order.
- *   - a DAG (sub-node shared by two parents) is walked exactly once.
- *   - an injected cycle (A ↔ B) terminates.
- *   - breadthBudget caps the descents per level.
- *   - maxDepth halts the recursion at the right level.
- *   - seeds start the walk mid-tree (alongside / instead of the root).
- *   - reasoning from the descend result is threaded onto the level; defaults
- *     to "" when omitted.
- *
- * Fixtures are plain in-memory `TreeIndex` objects — no disk, no workspace.
- */
-
-import { describe, expect, test } from "bun:test";
-
-import type { DescendResult } from "../traversal.js";
-import { resolveChildren, walkTree } from "../traversal.js";
-import type { ChildRef, TreeIndex } from "../tree-index.js";
-
-// ---------------------------------------------------------------------------
-// Fixture helpers
-// ---------------------------------------------------------------------------
-
-function page(ref: string): ChildRef {
-  return { kind: "page", ref };
-}
-
-function node(ref: string): ChildRef {
-  return { kind: "node", ref };
-}
-
-/**
- * Build a minimal in-memory `TreeIndex` from a forward-adjacency spec. Only
- * `childrenByNode` and `root` are exercised by the traversal, so the reverse
- * adjacency maps and `nodes` are left empty — the walk never reads them.
- */
-function makeTree(
-  root: string,
-  childrenByNode: Record<string, ChildRef[]>,
-): TreeIndex {
-  return {
-    nodes: new Map(),
-    childrenByNode: new Map(Object.entries(childrenByNode)),
-    parentsByNode: new Map(),
-    pageParents: new Map(),
-    root,
-  };
-}
-
-/**
- * Descend into every node child offered and keep every page child offered
- * (mechanical "descend all + keep all" stub — the old bulk-collect behavior).
- */
-function descendAll(
-  _nodeId: string,
-  children: ReadonlyArray<ChildRef>,
-): DescendResult {
-  return {
-    descend: children.filter((c) => c.kind === "node"),
-    keep: children.filter((c) => c.kind === "page"),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// resolveChildren
-// ---------------------------------------------------------------------------
-
-describe("resolveChildren", () => {
-  test("returns the ordered child refs for a known node", () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), page("p")],
-    });
-    expect(resolveChildren(tree, "_root")).toEqual([node("a"), page("p")]);
-  });
-
-  test("returns [] for a leaf / unknown node id", () => {
-    const tree = makeTree("_root", { _root: [] });
-    expect(resolveChildren(tree, "missing")).toEqual([]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Linear descent
-// ---------------------------------------------------------------------------
-
-describe("walkTree — linear descent", () => {
-  test("collects expected leaf pages and emits a level per walked node", async () => {
-    // _root → node:a → node:b → page:leaf  (plus a page on each level)
-    const tree = makeTree("_root", {
-      _root: [page("p-root"), node("a")],
-      a: [page("p-a"), node("b")],
-      b: [page("leaf")],
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend: descendAll,
-    });
-
-    expect([...pages].sort()).toEqual(["leaf", "p-a", "p-root"]);
-    expect(levels.map((l) => l.node)).toEqual(["_root", "a", "b"]);
-
-    expect(levels[0]).toMatchObject({
-      node: "_root",
-      considered: ["a"],
-      descended: ["a"],
-      skipped: [],
-      reasoning: "",
-    });
-    expect(levels[2]).toMatchObject({
-      node: "b",
-      considered: [],
-      descended: [],
-      skipped: [],
-    });
-  });
-
-  test("defaults start to tree.root", async () => {
-    const tree = makeTree("home", {
-      home: [page("only")],
-    });
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 4,
-      maxDepth: 4,
-      descend: descendAll,
-    });
-    expect([...pages]).toEqual(["only"]);
-    expect(levels.map((l) => l.node)).toEqual(["home"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// DAG dedup
-// ---------------------------------------------------------------------------
-
-describe("walkTree — DAG dedup", () => {
-  test("a sub-node shared by two parents is walked exactly once", async () => {
-    // _root → {node:left, node:right}; both → node:shared → page:s
-    const tree = makeTree("_root", {
-      _root: [node("left"), node("right")],
-      left: [node("shared")],
-      right: [node("shared")],
-      shared: [page("s")],
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend: descendAll,
-    });
-
-    expect([...pages]).toEqual(["s"]);
-    // `shared` appears once even though both left and right descend into it.
-    const walked = levels.map((l) => l.node);
-    expect(walked.filter((n) => n === "shared")).toHaveLength(1);
-    expect(walked.sort()).toEqual(["_root", "left", "right", "shared"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Cycle termination
-// ---------------------------------------------------------------------------
-
-describe("walkTree — cycle termination", () => {
-  test("an injected A ↔ B cycle terminates and walks each once", async () => {
-    const tree = makeTree("a", {
-      a: [node("b"), page("pa")],
-      b: [node("a"), page("pb")],
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 100,
-      descend: descendAll,
-    });
-
-    expect([...pages].sort()).toEqual(["pa", "pb"]);
-    const walked = levels.map((l) => l.node).sort();
-    expect(walked).toEqual(["a", "b"]);
-  });
-
-  test("a self-loop terminates", async () => {
-    const tree = makeTree("solo", {
-      solo: [node("solo"), page("p")],
-    });
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 4,
-      maxDepth: 100,
-      descend: descendAll,
-    });
-    expect([...pages]).toEqual(["p"]);
-    expect(levels.map((l) => l.node)).toEqual(["solo"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Breadth budget
-// ---------------------------------------------------------------------------
-
-describe("walkTree — breadthBudget", () => {
-  test("caps the descents per node and records the rest as skipped", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), node("b"), node("c"), node("d")],
-      a: [page("pa")],
-      b: [page("pb")],
-      c: [page("pc")],
-      d: [page("pd")],
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 2,
-      maxDepth: 8,
-      descend: descendAll,
-    });
-
-    const rootLevel = levels.find((l) => l.node === "_root")!;
-    expect(rootLevel.considered).toEqual(["a", "b", "c", "d"]);
-    expect(rootLevel.descended).toEqual(["a", "b"]);
-    expect(rootLevel.skipped).toEqual(["c", "d"]);
-
-    // Only the first two children's pages are reached.
-    expect([...pages].sort()).toEqual(["pa", "pb"]);
-    expect(levels.map((l) => l.node).sort()).toEqual(["_root", "a", "b"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Depth budget
-// ---------------------------------------------------------------------------
-
-describe("walkTree — maxDepth", () => {
-  test("halts recursion at the configured depth", async () => {
-    // _root(0) → a(1) → b(2) → c(3)
-    const tree = makeTree("_root", {
-      _root: [node("a")],
-      a: [node("b"), page("pa")],
-      b: [node("c"), page("pb")],
-      c: [page("pc")],
-    });
-
-    // maxDepth 1 walks depth 0 (_root) and depth 1 (a) only; b/c never walked.
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 1,
-      descend: descendAll,
-    });
-
-    expect(levels.map((l) => l.node)).toEqual(["_root", "a"]);
-    // `a`'s page is collected; b/c and their pages are not reached.
-    expect([...pages]).toEqual(["pa"]);
-  });
-
-  test("maxDepth 0 walks only the start level", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), page("pr")],
-      a: [page("pa")],
-    });
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 0,
-      descend: descendAll,
-    });
-    expect(levels.map((l) => l.node)).toEqual(["_root"]);
-    expect([...pages]).toEqual(["pr"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Seeds
-// ---------------------------------------------------------------------------
-
-describe("walkTree — seeds", () => {
-  test("seeds start the walk mid-tree alongside start", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), page("pr")],
-      a: [page("pa")],
-      mid: [page("pm"), node("deep")],
-      deep: [page("pd")],
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      seeds: ["mid"],
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend: descendAll,
-    });
-
-    // Both the root branch and the seeded `mid` subtree are explored.
-    expect([...pages].sort()).toEqual(["pa", "pd", "pm", "pr"]);
-    expect(levels.map((l) => l.node).sort()).toEqual([
-      "_root",
-      "a",
-      "deep",
-      "mid",
-    ]);
-  });
-
-  test("a node that is both start and seed is walked once", async () => {
-    const tree = makeTree("dup", {
-      dup: [page("p")],
-    });
-    const { levels } = await walkTree(tree, {
-      start: "dup",
-      seeds: ["dup"],
-      breadthBudget: 4,
-      maxDepth: 4,
-      descend: descendAll,
-    });
-    expect(levels.map((l) => l.node)).toEqual(["dup"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Descend decision threading
-// ---------------------------------------------------------------------------
-
-describe("walkTree — descend decision", () => {
-  test("threads the descend reasoning onto the level", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), node("b")],
-      a: [page("pa")],
-      b: [page("pb")],
-    });
-
-    const descend = (
-      _nodeId: string,
-      children: ReadonlyArray<ChildRef>,
-    ): DescendResult => ({
-      // Pick only "a"; keep every page child encountered.
-      descend: children.filter((c) => c.kind === "node" && c.ref === "a"),
-      keep: children.filter((c) => c.kind === "page"),
-      reasoning: "a is more relevant",
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend,
-    });
-
-    const rootLevel = levels.find((l) => l.node === "_root")!;
-    expect(rootLevel.reasoning).toBe("a is more relevant");
-    expect(rootLevel.descended).toEqual(["a"]);
-    expect(rootLevel.skipped).toEqual(["b"]);
-    expect([...pages]).toEqual(["pa"]);
-  });
-
-  test("ignores descend picks that were not offered node children", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), page("pr")],
-      a: [page("pa")],
-    });
-
-    const descend = (
-      _nodeId: string,
-      children: ReadonlyArray<ChildRef>,
-    ): DescendResult => ({
-      // "ghost" was never offered; "pr" is a page, not a node child.
-      descend: [node("ghost"), page("pr")],
-      keep: children.filter((c) => c.kind === "page"),
-    });
-
-    const { pages, levels } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend,
-    });
-
-    const rootLevel = levels.find((l) => l.node === "_root")!;
-    expect(rootLevel.considered).toEqual(["a"]);
-    expect(rootLevel.descended).toEqual([]);
-    expect(rootLevel.skipped).toEqual(["a"]);
-    // No node descent happened; only the root's own page is collected.
-    expect([...pages]).toEqual(["pr"]);
-    expect(levels.map((l) => l.node)).toEqual(["_root"]);
-  });
-
-  test("dedups repeated descend picks before applying breadthBudget", async () => {
-    const tree = makeTree("_root", {
-      _root: [node("a"), node("b")],
-      a: [page("pa")],
-      b: [page("pb")],
-    });
-
-    const descend = (): DescendResult => ({
-      // "a" repeated should count once; budget of 2 then still admits "b".
-      descend: [node("a"), node("a"), node("b")],
-      keep: [],
-    });
-
-    const { levels } = await walkTree(tree, {
-      breadthBudget: 2,
-      maxDepth: 8,
-      descend,
-    });
-
-    const rootLevel = levels.find((l) => l.node === "_root")!;
-    expect(rootLevel.descended).toEqual(["a", "b"]);
-    expect(rootLevel.skipped).toEqual([]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Page keeping
-// ---------------------------------------------------------------------------
-
-describe("walkTree — page keeping", () => {
-  test("collects only the kept page children, dropping the rest", async () => {
-    const tree = makeTree("_root", {
-      _root: [page("pr-keep"), page("pr-drop"), node("a")],
-      a: [page("pa-keep"), page("pa-drop")],
-    });
-
-    // Descend every node; keep only the pages whose slug ends in "-keep".
-    const descend = (
-      _nodeId: string,
-      children: ReadonlyArray<ChildRef>,
-    ): DescendResult => ({
-      descend: children.filter((c) => c.kind === "node"),
-      keep: children.filter(
-        (c) => c.kind === "page" && c.ref.endsWith("-keep"),
-      ),
-    });
-
-    const { pages } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend,
-    });
-
-    // The "-drop" pages were offered but not kept, so they never reach `pages`.
-    expect([...pages].sort()).toEqual(["pa-keep", "pr-keep"]);
-  });
-
-  test("ignores kept refs that were not offered page children of the node", async () => {
-    const tree = makeTree("_root", {
-      _root: [page("real"), node("a")],
-      a: [page("pa")],
-    });
-
-    const descend = (
-      _nodeId: string,
-      children: ReadonlyArray<ChildRef>,
-    ): DescendResult => ({
-      descend: children.filter((c) => c.kind === "node"),
-      // "ghost" was never offered; node("a") is a node, not a page — both are
-      // ignored. Only the genuinely-offered page children survive.
-      keep: [
-        page("ghost"),
-        node("a"),
-        ...children.filter((c) => c.kind === "page"),
-      ],
-    });
-
-    const { pages } = await walkTree(tree, {
-      breadthBudget: 8,
-      maxDepth: 8,
-      descend,
-    });
-
-    expect([...pages].sort()).toEqual(["pa", "real"]);
-  });
-});