Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import * as fs from "node:fs";
import * as os from "node:os";
import * as nodePath from "node:path";
import { createHash } from "node:crypto";
import { fileURLToPath } from "node:url";

import { saveIngestBaseline } from "../ingest-baseline.js";
import { fileIdentity, repoWorkspaceIdFor } from "../system.js";
import { canonicalWorkspacePath, verifyRecordPath } from "../config.js";
import { loadIngestionModules } from "../commands/ingestion-loader.js";
import { ingestFiles } from "../commands/ingest.js";
import { FakeBackend } from "./helpers/fake-backend.js";
import {
  classifyFile,
  diffNodes,
  expectedNodes,
  graphVerdict,
  loadVerifyRecord,
  pickVerifyFiles,
  recordFromReport,
  runVerify,
  saveVerifyRecord,
  storedNodes,
  VERIFY_DEFAULT_KINDS,
  verifyRecordOutdated,
  type VerifyNode,
  type VerifyReport,
} from "../verify.js";

/**
 * CL-24A: `ix verify` compares a re-parse with the stored nodes. These pin the
 * pure parts (sampling, node sets, the diff, the verdict) and, against a fake
 * client, the shapes that matter: stale vs diverged (F-01), multi-repo
 * identity, and the refusals.
 */

const node = (kind: string, name: string, lineStart: number | null = 1, lineEnd: number | null = 2): VerifyNode =>
  ({ kind, name, lineStart, lineEnd });

describe("pickVerifyFiles", () => {
  const root = "/w";
  const baseline = {
    files: new Map<string, number>([
      ["/w/a.ts", 1], ["/w/b.ts", 2], ["/w/c.ts", 3], ["/w/d.ts", 4], ["/w/e.ts", 5],
      ["/w/f.ts", 6], ["/w/g.ts", 7], ["/w/h.ts", 8], ["/w/slow.ts", 99], ["/w/x.unknown", 100],
    ]),
    replayedFiles: ["c.ts"],
    parseTimeouts: ["slow.ts"],
  };
  const supported = (rel: string) => !rel.endsWith(".unknown");

  it("is deterministic for a given seed", () => {
    const a = pickVerifyFiles(root, baseline, { sample: 6, seed: 7, supported });
    const b = pickVerifyFiles(root, baseline, { sample: 6, seed: 7, supported });
    expect(a).toEqual(b);
    expect(a).toHaveLength(6);
  });

  it("puts explicit paths first, then replayed files, then the newest", () => {
    const picked = pickVerifyFiles(root, baseline, { sample: 4, seed: 1, explicit: ["a.ts"], supported });
    expect(picked[0]).toBe("a.ts");
    expect(picked[1]).toBe("c.ts");
    // ceil(4/2) = 2 recent ones on top of the two already picked: h.ts is the newest eligible.
    expect(picked[2]).toBe("h.ts");
    expect(picked).toHaveLength(4);
  });

  it("skips parse timeouts and unsupported grammars", () => {
    const picked = pickVerifyFiles(root, baseline, { sample: 100, seed: 1, supported });
    expect(picked).not.toContain("slow.ts");
    expect(picked).not.toContain("x.unknown");
    expect(picked).toHaveLength(8);
  });

  it("reads workspace-relative baseline keys too", () => {
    const picked = pickVerifyFiles(root, { files: new Map([["src/a.ts", 1]]), replayedFiles: [], parseTimeouts: [] },
      { sample: 5, seed: 1 });
    expect(picked).toEqual(["src/a.ts"]);
  });
});

describe("expectedNodes", () => {
  it("drops chunk and external nodes, and maps section start_line/end_line", () => {
    const got = expectedNodes({ ops: [
      { type: "UpsertNode", id: "f", kind: "file", name: "a.md", attrs: { line_start: 1, line_end: 9 } },
      { type: "UpsertNode", id: "c", kind: "chunk", name: "body", attrs: { start_line: 1, end_line: 2 } },
      { type: "UpsertNode", id: "x", kind: "function", name: "ext", attrs: { external: true } },
      { type: "UpsertNode", id: "s", kind: "section", name: "Intro", attrs: { start_line: 3, end_line: 5 } },
      { type: "UpsertEdge", id: "e", src: "f", dst: "s", predicate: "CONTAINS" },
    ] });
    expect([...got.keys()]).toEqual(["f", "s"]);
    expect(got.get("s")).toEqual(node("section", "Intro", 3, 5));
  });
});

describe("storedNodes", () => {
  const row = (id: string, uri: string, extra: Record<string, unknown> = {}) => ({
    id, kind: "function", name: id, attrs: { line_start: 1, line_end: 2 }, provenance: { sourceUri: uri }, ...extra,
  });

  it("keeps an exact source path only, not a substring hit", () => {
    const got = storedNodes([row("a", "src/a.ts"), row("b", "src/a.ts.bak"), row("c", "lib/src/a.ts")], "src/a.ts");
    expect([...got.keys()]).toEqual(["a"]);
  });

  it("accepts both source_uri spellings and Windows separators", () => {
    const got = storedNodes([
      { id: "a", kind: "function", name: "a", attrs: {}, provenance: { source_uri: "src/a.ts" } } as any,
      row("b", "src\\a.ts"),
    ], "src\\a.ts");
    expect([...got.keys()].sort()).toEqual(["a", "b"]);
  });

  it("drops chunks, externals and tombstones", () => {
    const got = storedNodes([
      row("a", "a.ts", { kind: "chunk" }),
      row("b", "a.ts", { attrs: { external: true } }),
      row("c", "a.ts", { deletedRev: 4 }),
      row("d", "a.ts"),
    ], "a.ts");
    expect([...got.keys()]).toEqual(["d"]);
  });
});

describe("diffNodes", () => {
  it("reports missing, extra and changed name, kind and line spans", () => {
    const exp = new Map([["1", node("function", "f", 1, 5)], ["2", node("class", "C")], ["3", node("function", "g")]]);
    const got = new Map([["1", node("method", "f2", 2, 6)], ["2", node("class", "C")], ["4", node("function", "old")]]);
    const diff = diffNodes(exp, got);
    expect(diff.missing).toEqual([{ id: "3", kind: "function", name: "g" }]);
    expect(diff.extra).toEqual([{ id: "4", kind: "function", name: "old" }]);
    expect(diff.changed.map((c) => c.field).sort()).toEqual(["kind", "lineEnd", "lineStart", "name"]);
  });
});

describe("classifyFile", () => {
  const empty = { missing: [], extra: [], changed: [] };
  const missing = { missing: [{ id: "1", kind: "function", name: "f" }], extra: [], changed: [] };

  it("clean when hashes match and nodes match", () => {
    expect(classifyFile("h", "h", empty, false, 3)).toEqual({ state: "clean" });
  });
  it("stale when the bytes changed since ingest", () => {
    expect(classifyFile("h2", "h1", missing, false, 3).state).toBe("stale");
  });
  it("diverged when the hash is equal and nodes are missing", () => {
    expect(classifyFile("h", "h", missing, false, 0)).toEqual({ state: "diverged" });
  });
  it("F-01: the stored hash is the edit in between, so only a recorded replay makes it diverged", () => {
    // The backend's source hash is the newest stored patch's; an Idempotent
    // revert writes none, so the hashes differ even though nothing is pending.
    expect(classifyFile("h2", "h1", missing, false, 3, true)).toEqual({ state: "diverged", reason: "replayed_not_applied" });
    // Not recorded as replayed: indistinguishable from an edit since the map.
    expect(classifyFile("h2", "h1", missing, false, 3, false)).toEqual({ state: "stale", reason: "changed_since_ingest" });
  });
  it("unverified when truncated, with no comparison, or with no hash and no nodes", () => {
    expect(classifyFile("h", "h", empty, true).state).toBe("unverified");
    expect(classifyFile("h", "h", null, false).state).toBe("unverified");
    expect(classifyFile("h", undefined, missing, false, 0)).toEqual({ state: "unverified", reason: "not_in_graph" });
  });
  it("without a hash lookup, a match is still clean and a mismatch is not judged", () => {
    expect(classifyFile("h", null, empty, false, 1).state).toBe("clean");
    expect(classifyFile("h", null, missing, false, 1)).toEqual({ state: "unverified", reason: "hash_unknown" });
  });
});

describe("graphVerdict", () => {
  const map = "ix map";
  const rebuild = "ix reset --workspace --yes --ingest";
  // [clean, stale, diverged, unverified] -> verdict. `clean` only when some
  // file verified clean and none is stale or diverged.
  const cases: Array<[number, number, number, number, ReturnType<typeof graphVerdict>]> = [
    [0, 0, 0, 0, { graph: "unverified", fix: null, reason: "no_files" }],
    [20, 0, 0, 0, { graph: "clean", fix: null }],
    [1, 0, 0, 19, { graph: "clean", fix: null }],
    [0, 0, 0, 20, { graph: "unverified", fix: null, reason: "no_file_verified" }],
    // The two shapes from the review: nothing verified clean, nothing diverged.
    [0, 20, 0, 0, { graph: "stale", fix: map }],
    [0, 1, 0, 19, { graph: "stale", fix: map }],
    // A clean file beside a stale one still does not vouch for the stale one.
    [2, 1, 0, 0, { graph: "stale", fix: map }],
    [18, 1, 0, 1, { graph: "stale", fix: map }],
    // Stale files alone are not divergence; any diverged file is.
    [1, 1, 1, 0, { graph: "diverged", fix: rebuild }],
    [0, 0, 1, 19, { graph: "diverged", fix: rebuild }],
    [0, 5, 1, 0, { graph: "diverged", fix: rebuild }],
    [0, 0, 20, 0, { graph: "diverged", fix: rebuild }],
  ];
  it.each(cases)("clean=%i stale=%i diverged=%i unverified=%i", (clean, stale, diverged, unverified, want) => {
    const files = clean + stale + diverged + unverified;
    expect(graphVerdict({ files, clean, stale, diverged, unverified })).toEqual(want);
  });
});

// ── With a workspace on disk ────────────────────────────────────────────

let home: string;
let savedIxHome: string | undefined;

beforeEach(() => {
  // Canonical exactly as ingest makes its root (`canonicalWorkspacePath`, i.e.
  // realpathSync.native): plain realpathSync keeps a Windows 8.3 name like
  // RUNNER~1, which ingest -- and so verify -- expands.
  home = canonicalWorkspacePath(fs.mkdtempSync(nodePath.join(os.tmpdir(), "ix-verify-")));
  savedIxHome = process.env.IX_HOME;
  process.env.IX_HOME = home;
});

afterEach(() => {
  if (savedIxHome === undefined) delete process.env.IX_HOME;
  else process.env.IX_HOME = savedIxHome;
  fs.rmSync(home, { recursive: true, force: true });
});

function register(root: string, workspaceId = "ws1"): void {
  fs.writeFileSync(nodePath.join(home, "config.yaml"),
    `endpoint: http://127.0.0.1:1\nformat: text\nworkspaces:\n  - workspace_id: "${workspaceId}"\n` +
    `    workspace_name: repo\n    root_path: ${root}\n    default: true\n`);
}

const sha = (s: string) => createHash("sha256").update(Buffer.from(s)).digest("hex");

/** What ingest would have stored for `rel`, as `/v1/list` rows. */
async function ingestedRows(root: string, rel: string, workspaceId: string) {
  const [{ parseFile }, { buildPatchWithResolution, extractorName }] = await loadIngestionModules();
  const src = fs.readFileSync(nodePath.join(root, rel), "utf-8");
  const { fileWorkspaceId, fileMultiRepo } = fileIdentity(root, workspaceId);
  const build = buildPatchWithResolution as (...a: unknown[]) => { ops: Array<Record<string, any>> };
  const patch = build(parseFile(rel, src), sha(src), fileWorkspaceId(rel), [], undefined, fileMultiRepo(rel));
  return {
    extractor: extractorName(),
    ws: fileWorkspaceId(rel),
    hash: sha(src),
    rows: patch.ops.filter((o) => o.type === "UpsertNode").map((o) => ({
      id: o.id, kind: o.kind, name: o.name, attrs: o.attrs, provenance: { sourceUri: rel, sourceHash: sha(src) },
    })),
  };
}

function fakeClient(store: { rows: any[]; hashes: Array<{ workspaceId: string; uri: string; hash: string }>; stats?: boolean }) {
  const calls: Array<{ kind: string; scope?: string; workspaceId?: string }> = [];
  return {
    calls,
    client: {
      // /v1/stats byKind: every kind the store holds, as the backend counts them.
      ...(store.stats ? {
        async stats() {
          const kinds = [...new Set(store.rows.map((r) => r.kind as string))];
          return { nodes: { total: store.rows.length, byKind: kinds.map((kind) => ({ kind, count: 1 })) } };
        },
      } : {}),
      async listByKind(kind: string, opts?: { scope?: string; workspaceId?: string }) {
        calls.push({ kind, scope: opts?.scope, workspaceId: opts?.workspaceId });
        return store.rows.filter((r) => r.kind === kind && r.provenance.sourceUri.includes(opts?.scope ?? ""));
      },
      async getSourceHashes() { return store.hashes; },
    } as any,
  };
}

describe("runVerify", () => {
  it("is unverified/not_mapped with no workspace, and suggests ix map", async () => {
    const root = nodePath.join(home, "nowhere");
    fs.mkdirSync(root);
    const report = await runVerify(fakeClient({ rows: [], hashes: [] }).client, root);
    expect(report).toMatchObject({ graph: "unverified", reason: "not_mapped", fix: "ix map" });
  });

  it("refuses to judge when the extractor changed", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), "old-extractor/0");
    const report = await runVerify(fakeClient({ rows: [], hashes: [] }).client, root);
    expect(report).toMatchObject({ graph: "unverified", reason: "extractor_changed", fix: "ix map" });
  });

  it("clean, stale, and diverged (same bytes, nodes missing)", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    fs.writeFileSync(nodePath.join(root, "b.ts"), "export function b() { return 2; }\nexport class B {}\n");
    fs.writeFileSync(nodePath.join(root, "c.ts"), "export function c() { return 3; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    const b = await ingestedRows(root, "b.ts", "ws1");
    const c = await ingestedRows(root, "c.ts", "ws1");
    saveIngestBaseline(root, new Map(["a.ts", "b.ts", "c.ts"].map((f, i) => [nodePath.join(root, f), i])), 3,
      new Date(), new Map(), a.extractor);
    // b.ts: the graph lost its function (hash still current). c.ts: edited since ingest.
    const store = {
      rows: [...a.rows, ...b.rows.filter((r) => r.kind !== "function"), ...c.rows],
      hashes: [
        { workspaceId: "ws1", uri: "a.ts", hash: a.hash },
        { workspaceId: "ws1", uri: "b.ts", hash: b.hash },
        { workspaceId: "ws1", uri: "c.ts", hash: "older" },
      ],
    };
    const { client, calls } = fakeClient(store);
    const report = await runVerify(client, root, { sample: 10 });
    const state = Object.fromEntries(report.files.map((f) => [f.path, f.state]));
    expect(state).toEqual({ "a.ts": "clean", "b.ts": "diverged", "c.ts": "stale" });
    expect(report.graph).toBe("diverged");
    expect(report.fix).toBe("ix reset --workspace --yes --ingest");
    expect(report.files.find((f) => f.path === "b.ts")!.missing).toEqual([expect.objectContaining({ kind: "function", name: "b" })]);
    // Scoped, per-file workspace, never a chunk read.
    expect(calls.every((c) => c.workspaceId === "ws1" && c.kind !== "chunk")).toBe(true);
    // No edge fields anywhere in the report.
    expect(JSON.stringify(report)).not.toMatch(/edge|predicate|CONTAINS/i);
    // The record is saved for status/doctor.
    expect(loadVerifyRecord(root)).toMatchObject({ graph: "diverged", files: 3, diverged: 1, stale: 1, divergedFiles: ["b.ts"] });
  });

  it("diverged when the graph holds an extra node the re-parse does not (hash current)", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), a.extractor);
    // A leftover from an older edit that was never retracted.
    const fn = a.rows.find((r) => r.kind === "function")!;
    const ghost = { ...fn, id: "ghost-node-id", name: "removedLongAgo" };
    const { client } = fakeClient({ rows: [...a.rows, ghost], hashes: [{ workspaceId: "ws1", uri: "a.ts", hash: a.hash }] });
    const report = await runVerify(client, root, { sample: 10 });
    expect(report.graph).toBe("diverged");
    expect(report.files[0]).toMatchObject({ path: "a.ts", state: "diverged", missing: [] });
    expect(report.files[0].extra).toEqual([expect.objectContaining({ id: "ghost-node-id", name: "removedLongAgo" })]);
  });

  it("F-01 end to end: a recorded not-applied revert is diverged, an unrecorded one is only stale", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    // On disk: the reverted bytes. In the graph: the edit in between, whose
    // patch is still the newest, so its hash is the stored one.
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function between() { return 2; }\n");
    register(root);
    const between = await ingestedRows(root, "a.ts", "ws1");
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    const store = { rows: between.rows, hashes: [{ workspaceId: "ws1", uri: "a.ts", hash: between.hash }] };
    const ingestedAt = new Date(Date.now() + 5_000); // after the revert's mtime
    const files = new Map([[nodePath.join(root, "a.ts"), 1]]);

    saveIngestBaseline(root, files, 3, ingestedAt, new Map(), between.extractor, { replayedFiles: ["a.ts"] });
    const recorded = await runVerify(fakeClient(store).client, root, { sample: 5 });
    expect(recorded.files[0]).toMatchObject({ path: "a.ts", state: "diverged", reason: "replayed_not_applied" });
    expect(recorded.graph).toBe("diverged");

    saveIngestBaseline(root, files, 3, ingestedAt, new Map(), between.extractor);
    const unrecorded = await runVerify(fakeClient(store).client, root, { sample: 5 });
    expect(unrecorded.files[0]).toMatchObject({ path: "a.ts", state: "stale", reason: "changed_since_ingest" });
    expect(unrecorded.graph).toBe("stale");
  });

  it("reads every kind the workspace holds: a stored node of a kind the parse never produces is extra", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), a.extractor);
    // `section` is neither in VERIFY_DEFAULT_KINDS nor anything a .ts parse makes.
    expect(VERIFY_DEFAULT_KINDS).not.toContain("section");
    expect([...expectedNodes({ ops: [] }).values()]).toEqual([]);
    const leftover = { id: "old-section-id", kind: "section", name: "Old heading", attrs: { start_line: 1, end_line: 1 },
      provenance: { sourceUri: "a.ts", sourceHash: a.hash } };
    const store = { rows: [...a.rows, leftover], hashes: [{ workspaceId: "ws1", uri: "a.ts", hash: a.hash }], stats: true };
    const { client, calls } = fakeClient(store);
    const report = await runVerify(client, root, { sample: 5 });
    expect(calls.some((c) => c.kind === "section" && c.scope === "a.ts")).toBe(true);
    expect(report.graph).toBe("diverged");
    expect(report.files[0]).toMatchObject({ path: "a.ts", state: "diverged", missing: [] });
    expect(report.files[0].extra).toEqual([{ id: "old-section-id", kind: "section", name: "Old heading" }]);
  });

  it("a named path whose parse timed out, or over ingest's size limit, is unverified and never parsed", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "slow.ts"), "export function slow() { return 1; }\n");
    fs.writeFileSync(nodePath.join(root, "big.ts"), `export const big = "${"x".repeat(1024 * 1024)}";\n`);
    register(root);
    const [parser, builder, languages] = await loadIngestionModules();
    let parsed = 0;
    const loadModules = async (): Promise<Awaited<ReturnType<typeof loadIngestionModules>>> => [
      { ...parser, parseFile: (...args: Parameters<typeof parser.parseFile>) => { parsed++; return parser.parseFile(...args); } },
      builder,
      languages,
    ];
    saveIngestBaseline(root, new Map(), 3, new Date(), new Map(), builder.extractorName(), { parseTimeouts: ["slow.ts"] });
    const report = await runVerify(fakeClient({ rows: [], hashes: [] }).client, root, { paths: ["slow.ts", "big.ts"], sample: 2, loadModules });
    expect(report.files).toEqual([
      expect.objectContaining({ path: "slow.ts", state: "unverified", reason: "parse_timed_out" }),
      expect.objectContaining({ path: "big.ts", state: "unverified", reason: "too_large" }),
    ]);
    expect(parsed).toBe(0);
  });

  it("only a whole-root run saves the status record; named paths and record:false do not", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), a.extractor);
    const store = { rows: a.rows, hashes: [{ workspaceId: "ws1", uri: "a.ts", hash: a.hash }] };
    await runVerify(fakeClient(store).client, root, { paths: ["a.ts"] });
    await runVerify(fakeClient(store).client, root, { record: false });
    expect(fs.existsSync(verifyRecordPath(root))).toBe(false);
    await runVerify(fakeClient(store).client, root);
    expect(loadVerifyRecord(root)).toMatchObject({ graph: "clean", files: 1 });
  });

  it("a non-canonical root (trailing slash, '.', a symlink) finds the canonical baseline and record", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), a.extractor);
    const link = nodePath.join(home, "link");
    fs.symlinkSync(root, link);
    const store = { rows: a.rows, hashes: [{ workspaceId: "ws1", uri: "a.ts", hash: a.hash }] };
    for (const input of [`${root}/`, `${root}/.`, link]) {
      const report = await runVerify(fakeClient(store).client, input);
      expect(report).toMatchObject({ root, graph: "clean" });
      expect(loadVerifyRecord(input)).toMatchObject({ root, graph: "clean" });
    }
  });

  it("a failed list makes that file unverified, not a crash", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    fs.writeFileSync(nodePath.join(root, "a.ts"), "export function a() { return 1; }\n");
    register(root);
    const a = await ingestedRows(root, "a.ts", "ws1");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "a.ts"), 1]]), 3, new Date(), new Map(), a.extractor);
    const client = {
      async listByKind() { throw new Error("500: boom"); },
      async getSourceHashes() { throw new Error("404: not found"); },
    } as any;
    const report = await runVerify(client, root);
    expect(report.files).toEqual([expect.objectContaining({ path: "a.ts", state: "unverified", reason: "list_failed" })]);
    expect(report.graph).toBe("unverified");
  });

  it("a named directory is not_file, not missing_on_disk", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(nodePath.join(root, "dir.ts"), { recursive: true });
    register(root);
    const [, builder] = await loadIngestionModules();
    saveIngestBaseline(root, new Map(), 3, new Date(), new Map(), builder.extractorName());
    const report = await runVerify(fakeClient({ rows: [], hashes: [] }).client, root, { paths: ["dir.ts"], sample: 1 });
    expect(report.files).toEqual([expect.objectContaining({ path: "dir.ts", state: "unverified", reason: "not_file" })]);
  });

  it("budgetMs: stops starting reads when it runs out, leaves unjudged files out, and saves no record", async () => {
    const root = nodePath.join(home, "repo");
    fs.mkdirSync(root);
    const rels = ["a.ts", "b.ts", "c.ts"];
    for (const [i, rel] of rels.entries()) fs.writeFileSync(nodePath.join(root, rel), `export function f${i}() { return ${i}; }\n`);
    register(root);
    const [, builder] = await loadIngestionModules();
    saveIngestBaseline(root, new Map(rels.map((r) => [nodePath.join(root, r), 1])), 3, new Date(), new Map(), builder.extractorName());
    let lists = 0;
    const slow = {
      async listByKind() { lists++; await new Promise((r) => setTimeout(r, 40)); return []; },
      async getSourceHashes() { return []; },
    } as any;
    const report = await runVerify(slow, root, { sample: 3, budgetMs: 60 });
    expect(report.partial).toBe(true);
    // 11 default kinds x 3 files without a budget; a few reads at most with one.
    expect(lists).toBeLessThan(11 * 3);
    expect(report.files.length).toBeLessThan(3);
    expect(fs.existsSync(verifyRecordPath(root))).toBe(false);

    // Out of budget before anything is judged: unverified, and says why.
    const none = await runVerify(slow, root, { sample: 3, budgetMs: 0 });
    expect(none).toMatchObject({ graph: "unverified", reason: "timed_out", partial: true, files: [] });

    // No budget: complete, no `partial` key.
    const full = await runVerify(fakeClient({ rows: [], hashes: [] }).client, root, { sample: 3, record: false });
    expect(full.files).toHaveLength(3);
    expect("partial" in full).toBe(false);
  });

  it("multi-repo: per-repo workspace ids and member-relative ids, as ingest builds them", async () => {
    const root = nodePath.join(home, "system");
    for (const repo of ["repo-a", "repo-b"]) {
      fs.mkdirSync(nodePath.join(root, repo, ".git"), { recursive: true });
      fs.mkdirSync(nodePath.join(root, repo, "src"), { recursive: true });
      fs.writeFileSync(nodePath.join(root, repo, "package.json"), `{"name":"${repo}"}`);
      fs.writeFileSync(nodePath.join(root, repo, "src", "x.ts"), "export function x() { return 1; }\n");
    }
    const { fileWorkspaceId, fileMultiRepo } = fileIdentity(root, "system-ws");
    expect(fileWorkspaceId("repo-a/src/x.ts")).toBe(repoWorkspaceIdFor(root, "repo-a"));
    expect(fileWorkspaceId("repo-b/src/x.ts")).toBe(repoWorkspaceIdFor(root, "repo-b"));
    expect(fileMultiRepo("repo-a/src/x.ts")).toMatchObject({ repoId: "repo-a", systemId: expect.any(String) });

    // A member's node ids are the ids its own solo ingest gives it.
    const coIngested = await ingestedRows(root, "repo-a/src/x.ts", "system-ws");
    const solo = await ingestedRows(nodePath.join(root, "repo-a"), "src/x.ts", repoWorkspaceIdFor(root, "repo-a"));
    expect(coIngested.rows.map((r) => r.id).sort()).toEqual(solo.rows.map((r) => r.id).sort());
    expect(coIngested.ws).toBe(solo.ws);

    // And verify, run over the system, finds them clean.
    register(root, "system-ws");
    saveIngestBaseline(root, new Map([[nodePath.join(root, "repo-a/src/x.ts"), 1]]), 3, new Date(), new Map(), coIngested.extractor);
    const { client, calls } = fakeClient({
      rows: coIngested.rows,
      hashes: [{ workspaceId: coIngested.ws, uri: "repo-a/src/x.ts", hash: coIngested.hash }],
    });
    const report = await runVerify(client, root);
    expect(report.files).toEqual([expect.objectContaining({ path: "repo-a/src/x.ts", state: "clean" })]);
    expect(calls.every((c) => c.workspaceId === repoWorkspaceIdFor(root, "repo-a"))).toBe(true);
  });
});

describe("verify record", () => {
  const report: VerifyReport = {
    at: "2026-10-11T00:00:00.000Z", root: "/r", lastIngestAt: "2026-10-10T00:00:00.000Z",
    graph: "diverged", fix: "ix reset --workspace --yes --ingest", sample: 20, seed: 24,
    counts: { files: 2, clean: 1, stale: 0, diverged: 1, unverified: 0 },
    files: [
      { path: "a.ts", state: "clean", expectedNodes: 1, storedNodes: 1, missing: [], extra: [], changed: [] },
      { path: "b.ts", state: "diverged", expectedNodes: 2, storedNodes: 1, missing: [], extra: [], changed: [] },
    ],
  };

  it("round-trips", () => {
    expect(saveVerifyRecord(recordFromReport(report))).toBe(true);
    expect(loadVerifyRecord("/r")).toEqual(recordFromReport(report));
    expect(loadVerifyRecord("/other")).toBeNull();
  });

  it("is outdated once the workspace has been ingested after it ran", () => {
    const record = recordFromReport(report);
    expect(verifyRecordOutdated(record, report.lastIngestAt)).toBe(false);
    expect(verifyRecordOutdated(record, "2026-10-12T00:00:00.000Z")).toBe(true);
    expect(verifyRecordOutdated(record, null)).toBe(false);
    expect(verifyRecordOutdated({ lastIngestAt: null }, "2026-10-12T00:00:00.000Z")).toBe(true);
  });

  it("reads a corrupt record as null", () => {
    fs.writeFileSync(verifyRecordPath("/r"), "{not json");
    expect(loadVerifyRecord("/r")).toBeNull();
  });
});

describe("docs/llm-format.md", () => {
  // Every reason verify can emit is documented: a consumer branching on
  // `reason=` must not meet an undocumented value (e.g. `no_files`).
  it("lists every reason verify.ts emits", () => {
    const here = nodePath.dirname(fileURLToPath(import.meta.url));
    const src = fs.readFileSync(nodePath.join(here, "..", "verify.ts"), "utf-8");
    const doc = fs.readFileSync(nodePath.join(here, "..", "..", "..", "..", "docs", "llm-format.md"), "utf-8");
    const reasons = new Set<string>();
    for (const re of [/reason: "([a-z_]+)"/g, /unverified\("([a-z_]+)"/g, /"(?:unverified|stale|diverged)", "([a-z_]+)"\)/g]) {
      for (const m of src.matchAll(re)) reasons.add(m[1]);
    }
    expect(reasons).toContain("no_files");
    expect(reasons).toContain("parse_timed_out");
    for (const reason of reasons) expect(doc, reason).toMatch(new RegExp(`[\`=]${reason}\``));
  });
});

// ── Against a real ingest ───────────────────────────────────────────────

describe("runVerify after a real ingestFiles run", () => {
  // A real ingest: discovery, the parse pool and HTTP commits to a fake backend.
  vi.setConfig({ testTimeout: 30_000, hookTimeout: 30_000 });

  const envKeys = ["HOME", "USERPROFILE", "IX_ENDPOINT", "IX_LOCK_DIR"] as const;
  const savedEnv: Record<string, string | undefined> = {};
  let backend: FakeBackend;
  let endpoint: string;

  beforeEach(async () => {
    for (const k of envKeys) savedEnv[k] = process.env[k];
    backend = new FakeBackend();
    backend.rememberHashes = true;
    endpoint = await backend.start();
    process.env.HOME = home;
    process.env.USERPROFILE = home;
    process.env.IX_ENDPOINT = endpoint;
    process.env.IX_LOCK_DIR = nodePath.join(home, "locks");
  });

  afterEach(async () => {
    for (const k of envKeys) {
      if (savedEnv[k] === undefined) delete process.env[k];
      else process.env[k] = savedEnv[k];
    }
    await backend.stop();
  });

  /** What the fake backend holds after the run, as verify's client reads it. */
  async function storedByIngest() {
    const uris = [...backend.lastOps.keys()];
    const res = await fetch(`${endpoint}/v1/source-hashes`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ uris }),
    });
    const hashes = (await res.json()) as Array<{ workspaceId: string; uri: string; hash: string }>;
    const hashOf = new Map(hashes.map((h) => [h.uri, h.hash]));
    const rows = uris.flatMap((uri) => (backend.lastOps.get(uri) ?? [])
      .filter((o) => o.type === "UpsertNode")
      .map((o) => ({ id: o.id, kind: o.kind, name: o.name, attrs: o.attrs, provenance: { sourceUri: uri, sourceHash: hashOf.get(uri) } })));
    return { rows, hashes };
  }

  // Not built from verify's own identity code: the rows are what ingestFiles
  // actually committed, so verify and ingest drifting apart on a system
  // workspace (per-repo workspace id, repoId, systemId) turns this red.
  it("multi-repo: every file ingest committed verifies clean, under its member repo's workspace id", async () => {
    const root = nodePath.join(home, "system");
    const files = { "repo-a": "src/alpha.ts", "repo-b": "src/beta.ts" } as const;
    for (const [repo, rel] of Object.entries(files)) {
      fs.mkdirSync(nodePath.join(root, repo, ".git"), { recursive: true });
      fs.mkdirSync(nodePath.join(root, repo, "src"), { recursive: true });
      fs.writeFileSync(nodePath.join(root, repo, "package.json"), `{"name":"${repo}"}`);
      fs.writeFileSync(nodePath.join(root, repo, rel),
        `export function ${repo.replace("-", "_")}() { return 1; }\nexport class C${repo.slice(-1)} {}\n`);
    }

    await ingestFiles(root, { format: "text", force: true, suppressOutput: true, printSummary: false, mapMode: true });
    const store = await storedByIngest();
    const sourceFiles = Object.entries(files).map(([repo, rel]) => `${repo}/${rel}`);
    expect([...backend.lastOps.keys()]).toEqual(expect.arrayContaining(sourceFiles));
    // The premise: ingest really did key each member under its own workspace.
    for (const repo of Object.keys(files)) {
      expect(store.hashes).toContainEqual(expect.objectContaining({
        uri: `${repo}/${files[repo as keyof typeof files]}`, workspaceId: repoWorkspaceIdFor(root, repo),
      }));
    }

    const { client, calls } = fakeClient(store);
    const report = await runVerify(client, root, { paths: sourceFiles, sample: sourceFiles.length, record: false });
    expect(report.files.map((f) => [f.path, f.state]).sort()).toEqual(sourceFiles.map((p) => [p, "clean"]).sort());
    expect(report.graph).toBe("clean");
    for (const repo of Object.keys(files)) {
      expect(calls.some((c) => c.workspaceId === repoWorkspaceIdFor(root, repo))).toBe(true);
    }
  });
});