Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { execFileSync } from "node:child_process";
import fc from "fast-check";

import { ingestFiles } from "../commands/ingest.js";
import { FakeBackend } from "./helpers/fake-backend.js";
import { applyEdit, EDIT_KINDS, initialRepo, render, type Edit, type EditKind, type Lang, type Repo } from "./helpers/edit-fixture.js";

// Two parse workers rather than `cpus - 1`. Every ingest starts its own pool
// and this file runs a few hundred of them; at one worker per core that is
// over a gigabyte of grammars per run on a large machine.
vi.mock("node:os", async (importOriginal) => {
  const actual = await importOriginal<typeof import("node:os")>();
  return { ...actual, cpus: () => actual.cpus().slice(0, 3) };
});

/**
 * Incremental equals fresh: after any sequence of edits, the graph that
 * incremental `ix map` runs leave on the backend must equal the graph a fresh
 * map of the final tree writes into an empty backend.
 *
 * Every test drives the real `ingestFiles` (discovery, the worker parse pool,
 * the commit engine) against `FakeBackend` with `semantics` set, so the fake
 * stores the graph and answers commits the way Ix-memory does: a bulk commit
 * sweeps the edges of the files it carries, `/v1/patch` does not, a patch id
 * seen before is not written again, and `/v1/source-hashes` reports the head
 * patch. Graphs are compared by `graphSignature()`: live nodes as
 * `id kind name`, live edges as `id src dst predicate` plus their `tier` and
 * `confidence` attrs.
 *
 * Each class of defect has a fixed scenario. A class that fails on `main` is
 * marked `it.fails` with the card that fixes it; that card deletes the marker,
 * and from then on the test guards the fix. The two properties run random
 * sequences: one over the edits that are correct today, and one over every
 * edit, which passes in `head` mode once IN-04, IN-10 and IN-11 have landed.
 *
 * The fast-check seed is fixed so a marked test cannot pass by luck. Set
 * IX_EQUIV_SEED to explore other sequences, and IX_EQUIV_RUNS for more runs.
 */

type Semantics = "legacy" | "head";
type Signature = { nodes: string[]; edges: string[] };

const SEED = Number(process.env.IX_EQUIV_SEED ?? 20261002);
const RUNS = Number(process.env.IX_EQUIV_RUNS ?? 20);

/** Variables `ingestFiles` reads that a developer's shell could have set. */
const ENV_KEYS = [
  "HOME", "USERPROFILE", "IX_ENDPOINT", "IX_LOCK_DIR", "IX_HOME", "IX_DEBUG",
  "IX_COMMIT_FAILURE_LIMIT", "IX_COMMIT_HTTP_MAX_FILES", "IX_COMMIT_CONCURRENCY",
  "IX_STITCH_COOLDOWN_MS", "IX_STITCH_WAIT_MS", "IX_MAP_DEADLINE_MS",
] as const;

/**
 * One working tree, one backend and home for the incremental runs, and a new
 * backend and home for each reference ingest. The tree lives at the same path
 * for both, so both compute the same workspace id and patch ids.
 */
class World {
  readonly root = realpathSync.native(mkdtempSync(join(tmpdir(), "ix-equiv-")));
  readonly repo = join(this.root, "repo");
  backend!: FakeBackend;
  private home = "";
  private endpoint = "";
  private homes = 0;
  /** The tree as last written, so `write` touches only what changed. */
  private onDisk = new Map<string, string>();

  constructor(private readonly semantics: Semantics) {
    mkdirSync(this.repo);
    // Discovery prefers `git ls-files`, which keeps the walk order fixed.
    execFileSync("git", ["init", "-q"], { cwd: this.repo, stdio: "ignore" });
  }

  async start(): Promise<void> {
    [this.backend, this.home, this.endpoint] = await this.newBackend();
  }

  private async newBackend(): Promise<[FakeBackend, string, string]> {
    const backend = new FakeBackend({ semantics: this.semantics });
    const home = join(this.root, `home${++this.homes}`);
    mkdirSync(home);
    return [backend, home, await backend.start()];
  }

  /** Make the working tree match `repo`, and stage it so discovery sees it. */
  write(repo: Repo): void {
    const want = new Map([...repo].map(([p, fns]) => [p, render(p, fns)]));
    this.writeSources(want);
  }

  writeSources(want: Map<string, string>): void {
    for (const p of this.onDisk.keys()) if (!want.has(p)) rmSync(join(this.repo, p));
    for (const [p, text] of want) {
      if (this.onDisk.get(p) === text) continue;
      mkdirSync(dirname(join(this.repo, p)), { recursive: true });
      writeFileSync(join(this.repo, p), text, "utf8");
    }
    this.onDisk = new Map(want);
    execFileSync("git", ["add", "-A"], { cwd: this.repo, stdio: "ignore" });
  }

  private ingestWith(home: string, endpoint: string) {
    process.env.HOME = home;
    process.env.USERPROFILE = home;
    process.env.IX_ENDPOINT = endpoint;
    process.env.IX_LOCK_DIR = join(home, "locks");
    return ingestFiles(this.repo, {
      recursive: true, format: "json", printSummary: false, suppressOutput: true, mapMode: true,
    });
  }

  /** An incremental `ix map` against the long-lived backend. */
  map() {
    this.backend.resetRequests();
    return this.ingestWith(this.home, this.endpoint);
  }

  /** The graph a fresh map of the current tree writes into an empty backend. */
  async freshSignature(): Promise<Signature> {
    const [backend, home, endpoint] = await this.newBackend();
    try {
      await this.ingestWith(home, endpoint);
      return backend.graphSignature();
    } finally {
      await backend.stop();
    }
  }

  async stop(): Promise<void> {
    try {
      await this.backend?.stop();
    } finally {
      rmSync(this.root, { recursive: true, force: true });
    }
  }
}

/** The lines two signatures disagree on, with edge endpoints named. */
function signatureDiff(world: World, live: Signature, want: Signature): string {
  const named = (line: string) => {
    const [id, src, dst, predicate, ...attrs] = line.split(" ");
    return `${predicate} ${world.backend.nodeName(src!)} -> ${world.backend.nodeName(dst!)} (${id!.slice(0, 8)}) ${attrs.join(" ")}`;
  };
  const out: string[] = [];
  for (const key of ["nodes", "edges"] as const) {
    const show = key === "edges" ? named : (line: string) => line;
    const inLive = new Set(live[key]);
    const inWant = new Set(want[key]);
    for (const x of live[key]) if (!inWant.has(x)) out.push(`stale   ${show(x)}`);
    for (const x of want[key]) if (!inLive.has(x)) out.push(`missing ${show(x)}`);
  }
  return out.join("\n");
}

/**
 * Map the initial tree, map again after each edit, then compare the live graph
 * with a fresh map of the final tree. `check` runs after the last map, before
 * the comparison.
 */
async function runSequence(
  semantics: Semantics,
  edits: Edit[],
  opts: { langs?: Lang[]; check?: (world: World) => void } = {},
): Promise<void> {
  const world = new World(semantics);
  try {
    await world.start();
    let repo = initialRepo();
    const history: Repo[] = [repo];
    world.write(repo);
    await world.map();
    for (const edit of edits) {
      for (const state of applyEdit(repo, edit, history, opts.langs)) {
        repo = state;
        history.push(repo);
        world.write(repo);
        await world.map();
      }
    }
    opts.check?.(world);
    const live = world.backend.graphSignature();
    const want = await world.freshSignature();
    expect(signatureDiff(world, live, want), `graph after ${JSON.stringify(edits)} differs from a fresh map`).toBe("");
  } finally {
    await world.stop();
  }
}

const edit = (kind: EditKind, path?: string, b = 0): Edit => ({ kind, a: 0, b, path });

function property(semantics: Semantics, kinds: readonly EditKind[], langs?: Lang[]): Promise<void> {
  const edits = fc.array(
    fc.record({ kind: fc.constantFrom(...kinds), a: fc.nat(60), b: fc.nat(60) }),
    { minLength: 1, maxLength: 3 },
  );
  return fc.assert(
    fc.asyncProperty(edits, (es) => runSequence(semantics, es, { langs })),
    { numRuns: RUNS, seed: SEED },
  );
}

describe("incremental ix map equals a fresh map (fake backend)", () => {
  // Generous, because each property is a few hundred real ingests. Each one
  // takes about 0.2 s here.
  vi.setConfig({ testTimeout: 300_000 });

  const saved: Record<string, string | undefined> = {};
  beforeAll(() => {
    for (const k of ENV_KEYS) {
      saved[k] = process.env[k];
      delete process.env[k];
    }
  });
  afterAll(() => {
    for (const [k, v] of Object.entries(saved)) {
      if (v === undefined) delete process.env[k];
      else process.env[k] = v;
    }
  });

  it("the harness: two fresh maps of one tree give one graph", async () => {
    await runSequence("head", []);
  });

  it("changing an intermediate Scala superclass re-resolves subclass callers", async () => {
    const world = new World("head");
    try {
      await world.start();
      const sources = new Map([
        ["a.scala", "trait A { def run() = () }\n"],
        ["b.scala", "trait B { def run() = () }\n"],
        ["mid.scala", "class Mid extends A {}\n"],
        ["child.scala", "class Child extends Mid {}\n"],
        ["use.scala", "object Use { def use(x: Child) = x.run() }\n"],
      ]);
      world.writeSources(sources);
      await world.map();
      const before = world.backend.graphSignature();
      sources.set("mid.scala", "class Mid extends B {}\n");
      world.writeSources(sources);
      await world.map();
      const live = world.backend.graphSignature();
      const fresh = await world.freshSignature();
      expect(fresh.edges).not.toEqual(before.edges);
      expect(signatureDiff(world, live, fresh)).toBe("");
    } finally {
      await world.stop();
    }
  });

  it("changing an intermediate Java superclass re-resolves subclass callers", async () => {
    const world = new World("head");
    try {
      await world.start();
      const sources = new Map([
        ["src/p/A.java", "package p;\npublic class A {\n  public void run() {}\n}\n"],
        ["src/p/B.java", "package p;\npublic class B {\n  public void run() {}\n}\n"],
        ["src/p/Mid.java", "package p;\npublic class Mid extends A {\n}\n"],
        ["src/p/Child.java", "package p;\npublic class Child extends Mid {\n}\n"],
        ["src/q/Use.java", "package q;\nimport p.Child;\npublic class Use {\n  void use(Child x) {\n    x.run();\n  }\n}\n"],
      ]);
      world.writeSources(sources);
      await world.map();
      const before = world.backend.graphSignature();
      sources.set("src/p/Mid.java", "package p;\npublic class Mid extends B {\n}\n");
      world.writeSources(sources);
      await world.map();
      const live = world.backend.graphSignature();
      const fresh = await world.freshSignature();
      expect(fresh.edges).not.toEqual(before.edges);
      expect(signatureDiff(world, live, fresh)).toBe("");
    } finally {
      await world.stop();
    }
  });

  it("a superclass edit re-tiers a subclass caller's edge in place", async () => {
    // `x.run()` binds to A.run by name and by type, so the edge keeps its id;
    // only its tier and confidence depend on Child's parents in another file.
    const world = new World("head");
    try {
      await world.start();
      const sources = new Map([
        ["a.scala", "trait A { def run() = () }\n"],
        ["child.scala", "class Child extends A {}\n"],
        ["use.scala", "object Use { def use(x: Child) = x.run() }\n"],
      ]);
      world.writeSources(sources);
      await world.map();
      const [typed, ...more] = world.backend.edgesOfTier("type");
      expect(more, "one typed edge before the edit").toEqual([]);
      sources.set("child.scala", "class Child {}\n");
      world.writeSources(sources);
      await world.map();
      const live = world.backend.graphSignature();
      const fresh = await world.freshSignature();
      const id = typed!.split(" ")[0]!;
      const now = fresh.edges.find((line) => line.startsWith(`${id} `));
      expect(now, "the same edge, no longer typed").toBeDefined();
      expect(now).not.toEqual(typed);
      expect(signatureDiff(world, live, fresh)).toBe("");
    } finally {
      await world.stop();
    }
  });

  it("a re-map with nothing changed commits nothing", async () => {
    // A revert to the first state is a second map of an unchanged tree.
    await runSequence("head", [{ kind: "revert", a: 0, b: 0 }], {
      check: (world) => expect(world.backend.commitCount).toBe(0),
    });
  });

  it("a body edit to a TypeScript file keeps every edge", async () => {
    await runSequence("head", [edit("editBody", "web/calc.ts"), edit("addFunction", "web/report.ts")]);
  });

  // F-03. Before IN-09/IN-10 an edited Python or Java file was resolved
  // against the batch of changed files alone, so its cross-file CALLS were
  // re-pointed at phantom module nodes or dropped. It now resolves against the
  // symbol table, in every language.
  it("IN-10: a body edit to a Python or Java file keeps its cross-file edges", async () => {
    await runSequence("head", [edit("editBody", "pkg/app.py"), edit("editBody", "src/com/ex/App.java")]);
  });

  // F-07. A new file has no backend hash; before IN-01 that sent the whole
  // repository down the first-ingest path, every file parsed and sent again.
  it("IN-01: adding a file sends one patch", async () => {
    await runSequence("head", [edit("addFile", undefined, 0)], {
      langs: ["ts"],
      check: (world) => {
        const sent = world.backend.requests
          .filter((r) => r.path === "/v1/patches/bulk" || r.path === "/v1/patch")
          .reduce((sum, r) => sum + r.patches, 0);
        expect(sent, "patches on the wire").toBe(1);
      },
    });
  });

  // The persisted symbol table gives the index every language's symbols, so an
  // added Python or Java file takes the incremental path too: one patch, and
  // its cross-file calls resolve as a fresh map resolves them.
  it("IN-01/IN-10: an added Python or Java file sends one patch and keeps its cross-file calls", async () => {
    const onePatch = (world: World) => {
      const sent = world.backend.requests
        .filter((r) => r.path === "/v1/patches/bulk" || r.path === "/v1/patch")
        .reduce((sum, r) => sum + r.patches, 0);
      expect(sent, "patches on the wire").toBe(1);
    };
    await runSequence("head", [edit("addFile", undefined, 0)], { langs: ["py"], check: onePatch });
    await runSequence("head", [edit("addFile", undefined, 1)], { langs: ["java"], check: onePatch });
  });

  // F-04. Dropping the file's last import removes a node, the patch carries a
  // DeleteNode, and a delete-bearing patch went to `/v1/patch`, which does not
  // sweep: the removed CALLS and IMPORTS edges stayed live. A backend whose
  // bulk route applies deletes now takes it there, and nothing goes per file.
  it("IN-04: removing a file's last call retires its edges, with no /v1/patch", async () => {
    await runSequence("head", [edit("removeCall", "web/main.ts")], {
      check: (world) => {
        expect(world.backend.requests.filter((r) => r.path === "/v1/patch"), "per-file commits").toEqual([]);
      },
    });
  });

  // F-03. Files that call a renamed or deleted function are unchanged, so
  // nothing re-resolved them: their edges went when the name went, and when it
  // came back -- renamed back, or the file restored -- they never returned.
  // The run now re-resolves the files that refer to a changed name.
  it("IN-11: a called function renamed and renamed back re-binds its callers", async () => {
    await runSequence("head", [edit("renameFunction", "web/math.ts", 0), { kind: "revert", a: 0, b: 0 }]);
  });

  it("IN-11: restoring a deleted file re-binds its callers", async () => {
    await runSequence("head", [edit("deleteThenRestore", "web/math.ts")]);
  });

  it("IN-11: a re-map with nothing renamed re-sends no caller", async () => {
    await runSequence("head", [edit("editBody", "web/math.ts")], {
      check: (world) => {
        const sent = world.backend.requests
          .filter((r) => r.path === "/v1/patches/bulk" || r.path === "/v1/patch")
          .reduce((sum, r) => sum + r.patches, 0);
        expect(sent, "only the edited file").toBe(1);
      },
    });
  });

  it("a revert and a delete-then-restore re-apply, on a backend with BEW-03", async () => {
    await runSequence("head", [edit("addFunction", "web/main.ts"), { kind: "revert", a: 0, b: 0 }]);
    await runSequence("head", [edit("deleteThenRestore", "web/main.ts")]);
  });

  // F-01, on the backend as shipped. The reverted file's patch id was
  // committed before, so the backend answers Idempotent, writes nothing, and
  // the graph keeps the edit. BEW-03 fixes it in the backend and IN-02 makes
  // the CLI report it. This one stays marked: `legacy` is the old backend.
  it.fails("F-01: a revert is lost on a backend without BEW-03", async () => {
    await runSequence("legacy", [edit("addFunction", "web/main.ts"), { kind: "revert", a: 0, b: 0 }]);
  });

  it("random TypeScript edits that add or change code", async () => {
    await property("head", ["editBody", "addFunction", "addCall", "addFile"], ["ts"]);
  });

  // The acceptance gate for the F-03 chain: IN-04, IN-10 and IN-11. All
  // three have landed, so it is no longer marked.
  it("IN-11: random edit sequences of every kind", async () => {
    await property("head", EDIT_KINDS);
  });
});