Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

11.0 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { describe, expect, it } from "vitest";

import type { IxClient } from "../../client/api.js";
import { collectFacts } from "../explain/facts.js";

const TARGET = "00000000-0000-0000-0000-000000000001";
const CALLEE = "00000000-0000-0000-0000-000000000002";
const DEPENDENT = "00000000-0000-0000-0000-000000000003";

interface Call {
  method: string;
  id: string;
  predicates?: string[];
  hops?: number;
}

/**
 * A graph where the target calls one function and is imported by one file,
 * so every optional step `collectFacts` can take has something to do: the
 * dependency tree has a node to walk, and the callee list has a callee to look
 * up.
 */
function fakeClient(calls: Call[]): IxClient {
  const node = (id: string, name: string, kind: string) => ({
    id, name, kind, attrs: {}, provenance: { sourceUri: `src/${name}.ts` },
  });
  return {
    async entity(id: string) {
      calls.push({ method: "entity", id });
      return {
        node: node(id, id === TARGET ? "config" : "callee", "function"),
        claims: [],
        decisions: [],
        edges: id === TARGET ? [{ src: TARGET, dst: CALLEE, predicate: "CALLS" }] : [],
      };
    },
    async expand(id: string, opts?: { direction?: string; predicates?: string[]; hops?: number }) {
      calls.push({ method: "expand", id, predicates: opts?.predicates, hops: opts?.hops });
      const importedBy = id === TARGET && opts?.direction === "in" && opts.predicates?.includes("IMPORTS");
      const calls_out = id === TARGET && opts?.direction === "out" && opts.predicates?.includes("CALLS");
      if (importedBy) {
        return { nodes: [node(DEPENDENT, "user", "file")], edges: [{ src: DEPENDENT, dst: TARGET, predicate: "IMPORTS" }] };
      }
      if (calls_out) {
        return { nodes: [node(CALLEE, "callee", "function")], edges: [{ src: TARGET, dst: CALLEE, predicate: "CALLS" }] };
      }
      return { nodes: [], edges: [] };
    },
    async provenance(id: string) {
      calls.push({ method: "provenance", id });
      return { entityId: id, chain: [{}, {}] };
    },
  } as unknown as IxClient;
}

describe("collectFacts scope", () => {
  it("fetches only what `ix context` reads", async () => {
    const calls: Call[] = [];

    const facts = await collectFacts(fakeClient(calls), TARGET, "config", "function", "context");

    // One entity, six fixed expands on the target (the sixth is the outbound
    // IMPORTS the bundle navigates by), one provenance, and one CONTAINS per
    // neighbouring file -- capped, so nothing here grows with the graph.
    const expands = calls.filter((c) => c.method === "expand");
    expect(expands.filter((c) => c.id === TARGET)).toHaveLength(6);
    expect(calls.some((c) => c.method === "expand" && c.predicates?.[0] === "IMPORTS"
                            && c.id === TARGET)).toBe(true);
    // The one neighbour in this graph is the file that imports the target.
    expect(expands.filter((c) => c.id !== TARGET))
      .toEqual([{ method: "expand", id: DEPENDENT, predicates: ["CONTAINS"], hops: undefined }]);
    // No entity lookups beyond the target, and no hierarchy walk: the
    // neighbour hop is expands only, and bounded.
    expect(calls.filter((c) => c.method === "entity").map((c) => c.id)).toEqual([TARGET]);
    expect(calls.some((c) => c.predicates?.includes("IN_REGION"))).toBe(false);

    expect(facts.topDependents).toEqual(["user"]);
    // The fake graph's only outbound edge is the target's CALLS to CALLEE.
    expect(facts.calleeRefs?.map((r) => r.name)).toEqual(["callee"]);
    expect(facts.historyLength).toBe(2);
    // Handed on so `ix context` does not fetch the same provenance twice.
    expect(calls.filter((c) => c.method === "provenance")).toHaveLength(1);
    expect(facts.provenance).toEqual({ entityId: TARGET, chain: [{}, {}] });
    // Absent, not zeroed: a skipped fact must not read as a measured one.
    expect(facts).not.toHaveProperty("downstreamDependents");
    expect(facts).not.toHaveProperty("callList");
    expect(facts).not.toHaveProperty("systemPath");
  });

  it("still collects everything `ix explain` renders", async () => {
    const calls: Call[] = [];

    const facts = await collectFacts(fakeClient(calls), TARGET, "config", "function");

    expect(calls.some((c) => c.id === DEPENDENT)).toBe(true);
    expect(calls.some((c) => c.predicates?.includes("IN_REGION"))).toBe(true);
    expect(calls.filter((c) => c.method === "entity").map((c) => c.id)).toContain(CALLEE);
    expect(facts.downstreamDependents).toBeGreaterThan(0);
    expect(facts.callList?.map((c) => c.name)).toEqual(["callee"]);
  });
});

/**
 * A file whose members the backend returns in an unhelpful order, with usage
 * recorded per member: `uses[id]` lists the files that use it.
 */
function fileWithMembers(
  calls: Call[],
  members: Array<{ id: string; name: string; kind?: string; lines?: [number, number] }>,
  uses: Record<string, string[]>,
  failing = new Set<string>(),
): IxClient {
  const memberNode = (m: (typeof members)[number]) => ({
    id: m.id, name: m.name, kind: m.kind ?? "function",
    attrs: m.lines ? { line_start: m.lines[0], line_end: m.lines[1] } : {},
    provenance: { sourceUri: "src/config.ts" },
  });
  return {
    async entity(id: string) {
      calls.push({ method: "entity", id });
      return { node: { id, name: "config.ts", kind: "file", attrs: {}, provenance: { sourceUri: "src/config.ts" } }, edges: [] };
    },
    async expand(id: string, opts?: { direction?: string; predicates?: string[]; limit?: number }) {
      calls.push({ method: "expand", id, predicates: opts?.predicates, hops: opts?.limit });
      if (id === TARGET && opts?.predicates?.[0] === "CONTAINS") {
        return { nodes: members.map(memberNode), edges: [] };
      }
      if (id !== TARGET) {
        if (failing.has(id)) throw new Error("backend unavailable");
        const nodes = (uses[id] ?? []).map((file, i) => ({
          id: `${id}-user-${i}`, name: `user${i}`, kind: "function", provenance: { sourceUri: file },
        }));
        return { nodes, edges: [] };
      }
      return { nodes: [], edges: [] };
    },
    async provenance(id: string) {
      calls.push({ method: "provenance", id });
      return { entityId: id, chain: [] };
    },
  } as unknown as IxClient;
}

describe("neighbour members", () => {
  it("takes one member from each neighbouring file before a second from any", async () => {
    // The evidence budget cuts the tail, and four members of the first import
    // crowded out every other file's -- including the file with the answer.
    const files = ["f-a", "f-b"];
    const client = {
      async entity(id: string) {
        return { node: { id, name: "entry.ts", kind: "file", attrs: {}, provenance: { sourceUri: "src/entry.ts" } }, edges: [] };
      },
      async expand(id: string, opts?: { direction?: string; predicates?: string[] }) {
        if (id === TARGET && opts?.direction === "out" && opts.predicates?.includes("IMPORTS")) {
          return { nodes: files.map((f, i) => ({ id: f, name: `dep${i}.ts`, kind: "file", attrs: {},
                                                 provenance: { sourceUri: `src/dep${i}.ts` } })), edges: [] };
        }
        if (files.includes(id)) {
          const which = id.slice(-1);
          return { nodes: [1, 2, 3].map(n => ({ id: `${id}-m${n}`, name: `${which}${n}`, kind: "function",
                                                attrs: { line_start: n * 10, line_end: n * 10 + 9 - n },
                                                provenance: { sourceUri: `src/dep.ts` } })), edges: [] };
        }
        return { nodes: [], edges: [] };
      },
      async provenance(id: string) { return { entityId: id, chain: [] }; },
    } as unknown as IxClient;

    const facts = await collectFacts(client, TARGET, "entry.ts", "file", "context");

    expect(facts.neighbourRefs?.slice(0, 4).map(r => r.name)).toEqual(["a1", "b1", "a2", "b2"]);
  });
});

describe("collectFacts member ranking", () => {
  const members = [
    { id: "m-real", name: "real", lines: [40, 41] as [number, number] },
    { id: "m-const", name: "DEFAULTS", kind: "variable", lines: [1, 30] as [number, number] },
    { id: "m-resolve", name: "resolveWorkspaceRoot", lines: [322, 342] as [number, number] },
    { id: "m-local", name: "localHelper", lines: [50, 60] as [number, number] },
  ];
  const uses = {
    "m-real": ["src/config.ts", "src/config.ts", "src/config.ts"],
    "m-resolve": ["src/a.ts", "src/b.ts", "src/b.ts", "src/config.ts"],
    "m-local": ["src/config.ts"],
  };

  it("ranks members used from other files first, for ix context", async () => {
    const calls: Call[] = [];
    const facts = await collectFacts(fileWithMembers(calls, members, uses), TARGET, "config.ts", "file", "context");

    expect(facts.members).toEqual(["resolveWorkspaceRoot", "real", "localHelper", "DEFAULTS"]);
    expect(facts.memberRefs?.[0]).toMatchObject({
      id: "m-resolve", path: "src/config.ts", lineStart: 322, lineEnd: 342, usedBy: 4, usedFromFiles: 2,
    });
    expect(facts.memberRefs?.[1]).toMatchObject({ usedBy: 3, usedFromFiles: 0 });
    // Bounded reads: the usage probe asks the backend for at most 50 users.
    const probes = calls.filter((c) => c.method === "expand" && c.id !== TARGET);
    expect(probes).toHaveLength(4);
    expect(probes.every((c) => c.hops === 50)).toBe(true);
  });

  it("leaves ix explain's member order, and its request count, alone", async () => {
    const calls: Call[] = [];
    const facts = await collectFacts(fileWithMembers(calls, members, uses), TARGET, "config.ts", "file");

    expect(facts.members).toEqual(["real", "DEFAULTS", "resolveWorkspaceRoot", "localHelper"]);
    expect(facts.memberRefs?.every((m) => m.usedBy === undefined)).toBe(true);
    expect(calls.some((c) => c.method === "expand" && c.id.startsWith("m-"))).toBe(false);
  });

  it("probes at most 40 members, chosen by kind and size", async () => {
    const many = Array.from({ length: 45 }, (_, i) => ({
      id: `m-${i}`, name: `fn${String(i).padStart(2, "0")}`, lines: [i + 1, i + 1 + i] as [number, number],
    }));
    const calls: Call[] = [];
    const facts = await collectFacts(fileWithMembers(calls, many, {}), TARGET, "config.ts", "file", "context");

    const probed = calls.filter((c) => c.method === "expand" && c.id !== TARGET).map((c) => c.id);
    expect(probed).toHaveLength(40);
    // The five smallest are the ones left unprobed, and they come last.
    expect(probed).not.toContain("m-0");
    expect(facts.memberRefs?.slice(-5).map((m) => m.id)).toEqual(["m-4", "m-3", "m-2", "m-1", "m-0"]);
    expect(facts.members).toHaveLength(45);
  });

  it("keeps a member it could not measure, below the measured ones", async () => {
    const calls: Call[] = [];
    const facts = await collectFacts(
      fileWithMembers(calls, members, uses, new Set(["m-resolve"])),
      TARGET, "config.ts", "file", "context",
    );

    expect(facts.members).toContain("resolveWorkspaceRoot");
    expect(facts.memberRefs?.find((m) => m.id === "m-resolve")?.usedBy).toBeUndefined();
    expect(facts.members[0]).toBe("real");
    expect(facts.members.at(-1)).toBe("resolveWorkspaceRoot");
  });
});