@intentius/chant 0.124.45 → 0.124.48

package/src/cli/handlers/search-live.test.ts

@@ -44,6 +44,11 @@ vi.mock("../../build", async () => {
   };
 });
 
+import type { ResourceMetadata } from "../../lexicon";
+import type { RootRead } from "../../observation";
+import searchSchema from "../../workspace/search.schema.json";
+import { contract } from "../../workspace/__fixtures__/contract-repo";
+const { expectValid } = contract(searchSchema);
 const { runSearch } = await import("./search");
 
 function decl<T extends object>(base: T): Declarable & T {
@@ -215,3 +220,385 @@ describe("search --live run-level notes (#1265)", () => {
     expect(all.indexOf("(no matches)")).toBeLessThan(all.findIndex((l) => l.includes("ownership filter unavailable")));
   });
 });
+
+// #4358 — a terraform root's blocks exist only once `buildRoots()` renders the
+// root, and `--live` built without it, so no terraform root was ever observed
+// and a plan attribute could never be matched. The live path now builds roots
+// and joins them to the declared canvas, as `chant graph --live` does.
+describe("search --live over build-root entities (#4358)", () => {
+  let out: string[];
+
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { out.push(`ERR ${s}`); });
+    discoverMock.mockReset();
+    discoverMock.mockImplementation(async () => ({ entities: new Map(), errors: [], sourceFiles: [] }));
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["terraform"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+  });
+
+  test("builds roots, observes their blocks and matches the attributes the read put on them", async () => {
+    const rooted = new Map<string, Declarable>([
+      ["app/terraform_data.replaced", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })],
+    ]);
+    buildResultMock.mockReset();
+    buildResultMock.mockImplementation((_src: unknown, _s: unknown, _x: unknown, opts?: { buildRoots?: unknown[] }) => ({
+      errors: [],
+      entities: (opts?.buildRoots?.length ?? 0) > 0 ? rooted : new Map(),
+      outputs: new Map([["terraform", ""]]),
+      warnings: [],
+    }));
+    loadPluginsMock.mockResolvedValue([
+      {
+        // createMockPlugin has no `buildRoots` option; the hook is spread on.
+        ...createMockPlugin({
+          name: "terraform",
+          describeResources: async ({ entityNames }: { entityNames: string[] }) =>
+            Object.fromEntries(
+            entityNames.map((n) => [n, { type: "Terraform::Resource", physicalId: "id-1", status: "managed", ownership: "owned", owned: true, attributes: { planAction: "replace" } }]),
+            ),
+        }),
+        buildRoots: async () => ({ entities: rooted, warnings: [] }),
+      },
+    ]);
+    const exit = await runSearch({ args: makeArgs({ path: "attr:planAction=replace" }), plugins: [], serializers: [] });
+    expect(out.join("\n")).toContain("app/terraform_data.replaced  terraform_data  id-1");
+    expect(exit).toBe(0);
+  });
+});
+
+// #4372 — a planned create is absent, and the plan's attributes ride beside
+// the verdict as annotations. The handler puts them on the declared row, so
+// `attr:planAction=create` matches a block that does not exist yet, and the
+// row still has no physical id.
+describe("search --live over a planned create (#4372)", () => {
+  let out: string[];
+
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { out.push(`ERR ${s}`); });
+    discoverMock.mockReset();
+    discoverMock.mockImplementation(async () => ({ entities: new Map(), errors: [], sourceFiles: [] }));
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["terraform"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+  });
+
+  test("attr:planAction=create and attr:planAfterUnknown=id match it, and it stays without a physical id", async () => {
+    const rooted = new Map<string, Declarable>([
+      ["app/terraform_data.replaced", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })],
+      ["app/terraform_data.created", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })],
+    ]);
+    buildResultMock.mockReset();
+    buildResultMock.mockImplementation((_src: unknown, _s: unknown, _x: unknown, opts?: { buildRoots?: unknown[] }) => ({
+      errors: [],
+      entities: (opts?.buildRoots?.length ?? 0) > 0 ? rooted : new Map(),
+      outputs: new Map([["terraform", ""]]),
+      warnings: [],
+    }));
+    loadPluginsMock.mockResolvedValue([
+      {
+        ...createMockPlugin({
+          name: "terraform",
+          describeResources: async () => ({
+            observation: "v1",
+            resources: {
+              "app/terraform_data.replaced": { type: "Terraform::Resource", physicalId: "id-1", status: "managed", ownership: "owned", attributes: { planAction: "replace" } },
+            },
+            annotations: { "app/terraform_data.created": { planAction: "create", planAfterUnknown: ["id", "input"] } },
+          }),
+        }),
+        buildRoots: async () => ({ entities: rooted, warnings: [] }),
+      },
+    ]);
+
+    expect(await runSearch({ args: makeArgs({ path: "attr:planAction=create", json: true }), plugins: [], serializers: [] })).toBe(0);
+    const json = JSON.parse(out.filter((l) => !l.startsWith("ERR ")).join("\n")) as { matches: Array<{ id: string; physicalId?: string | null }> };
+    expect(json.matches.map((m) => m.id)).toEqual(["app/terraform_data.created"]);
+    expect(json.matches[0]!.physicalId ?? null).toBeNull();
+
+    out = [];
+    expect(await runSearch({ args: makeArgs({ path: "attr:planAfterUnknown=id" }), plugins: [], serializers: [] })).toBe(0);
+    const text = out.join("\n");
+    expect(text).toContain("app/terraform_data.created");
+    expect(text).not.toContain("app/terraform_data.replaced");
+  });
+});
+
+// #4381 — when every match is a planned create, the live read worked and found
+// nothing bound yet. "returned no bound resources" read like a failed read.
+describe("search --live provenance when every match is a planned create (#4381)", () => {
+  let out: string[];
+
+  function setup(annotations: Record<string, Record<string, unknown>> | undefined, names: string[]) {
+    const rooted = new Map<string, Declarable>(
+      names.map((n) => [n, decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })]),
+    );
+    buildResultMock.mockReset();
+    buildResultMock.mockImplementation((_src: unknown, _s: unknown, _x: unknown, opts?: { buildRoots?: unknown[] }) => ({
+      errors: [],
+      entities: (opts?.buildRoots?.length ?? 0) > 0 ? rooted : new Map(),
+      outputs: new Map([["terraform", ""]]),
+      warnings: [],
+    }));
+    loadPluginsMock.mockResolvedValue([
+      {
+        ...createMockPlugin({
+          name: "terraform",
+          describeResources: async () => ({ observation: "v1", resources: {}, ...(annotations ? { annotations } : {}) }),
+        }),
+        buildRoots: async () => ({ entities: rooted, warnings: [] }),
+      },
+    ]);
+  }
+
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { out.push(`ERR ${s}`); });
+    discoverMock.mockReset();
+    discoverMock.mockImplementation(async () => ({ entities: new Map(), errors: [], sourceFiles: [] }));
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["terraform"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+  });
+
+  const planned = { "app/a": { planAction: "create" }, "app/b": { planAction: "create" } };
+
+  test("text footer and --json provenance say planned creates, and plannedCreates carries the count", async () => {
+    setup(planned, ["app/a", "app/b"]);
+    expect(await runSearch({ args: makeArgs({ path: "attr:planAction=create" }), plugins: [], serializers: [] })).toBe(0);
+    const text = out.join("\n");
+    expect(text).toContain("2 planned creates, none bound yet");
+    expect(text).not.toContain("returned no bound resources");
+
+    out = [];
+    expect(await runSearch({ args: makeArgs({ path: "attr:planAction=create", json: true }), plugins: [], serializers: [] })).toBe(0);
+    const doc = JSON.parse(out.filter((l) => !l.startsWith("ERR ")).join("\n")) as { provenance: string; plannedCreates?: number };
+    expectValid(doc);
+    expect(doc.provenance).toContain("2 planned creates, none bound yet");
+    expect(doc.plannedCreates).toBe(2);
+  });
+
+  test("a real empty live read keeps its wording and carries no plannedCreates", async () => {
+    setup(undefined, ["app/a", "app/b"]);
+    expect(await runSearch({ args: makeArgs({ path: "kind:Terraform::Resource" }), plugins: [], serializers: [] })).toBe(0);
+    expect(out.join("\n")).toContain("live read returned no bound resources");
+    expect(out.join("\n")).not.toContain("planned create");
+
+    out = [];
+    expect(await runSearch({ args: makeArgs({ path: "kind:Terraform::Resource", json: true }), plugins: [], serializers: [] })).toBe(0);
+    const doc = JSON.parse(out.filter((l) => !l.startsWith("ERR ")).join("\n")) as { provenance: string; plannedCreates?: number };
+    expectValid(doc);
+    expect(doc.provenance).toContain("live read returned no bound resources");
+    expect(doc.plannedCreates).toBeUndefined();
+  });
+});
+
+// #4384 - a plan-depth answer said "observed live". Each row carries the read
+// that answered it (`sources`, #2267), and the line and --json name it.
+describe("search --live names the plan read (#4384)", () => {
+  let out: string[];
+  const entities = new Map<string, Declarable>([
+    ["orders", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} })],
+  ]);
+  const PLAN_NOTE = "terraform.roots.app: the plan read answered (`terraform plan -input=false -lock=false -out=<tmp>/plan.tfplan`)";
+  const STATE_NOTE = "terraform.roots.app: the plan read failed (no provider credentials: x), so the state read answered; plan attributes are absent";
+  const DECLARED_NOTE = "terraform.roots.app: no read answered, declared only (the plan read could not reach the backend)";
+
+  const FELL_TO_STATE: Record<string, RootRead> = { "terraform.roots.app": { depth: "plan", fellBackTo: "state", reason: "no-credentials" } };
+  const FELL_TO_DECLARED: Record<string, RootRead> = { "terraform.roots.app": { depth: "plan", fellBackTo: "declared", reason: "backend-unreachable" } };
+
+  function setup(
+    sources: Record<string, string>,
+    notes: string[],
+    resources: Record<string, ResourceMetadata> | null = null,
+    rootReads?: Record<string, RootRead>,
+  ) {
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "terraform",
+        describeResources: async () => ({
+          observation: "v1" as const,
+          resources: resources ?? { orders: { type: "Terraform::Resource", physicalId: "db-1", status: "OK", ownership: "owned" as const } },
+          sources,
+          notes,
+          ...(rootReads ? { rootReads } : {}),
+        }),
+      }),
+    ]);
+  }
+
+  async function run(json = false) {
+    out = [];
+    const exit = await runSearch({ args: makeArgs({ path: "kind:Terraform::Resource", json }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    return out.filter((l) => !l.startsWith("ERR ")).join("\n");
+  }
+
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { out.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { out.push(`ERR ${s}`); });
+    discoverMock.mockReset();
+    discoverMock.mockResolvedValue({ entities, errors: [], sourceFiles: [] });
+    buildResultMock.mockReset();
+    buildResultMock.mockReturnValue({ errors: [], entities, outputs: new Map([["terraform", ""]]), warnings: [] });
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveLexMock.mockReset();
+    resolveLexMock.mockResolvedValue(["terraform"]);
+    hasSnapshotMock.mockReset();
+    hasSnapshotMock.mockResolvedValue(false);
+  });
+
+  test("a plan answer names the plan depth in the line and in --json", async () => {
+    setup({ orders: "plan" }, [PLAN_NOTE]);
+    expect(await run()).toContain("observed at the plan depth (terraform plan -lock=false) · bound 1/1");
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source).toMatchObject({ kind: "live", depth: "plan", reads: ["plan"] });
+    expect(doc.provenance).toBe("observed at the plan depth (terraform plan -lock=false) · bound 1/1");
+  });
+
+  test("a live+plan answer names both reads", async () => {
+    setup({ orders: "live+plan" }, [PLAN_NOTE]);
+    const text = await run();
+    expect(text).toContain("observed live and at the plan depth (live-plan -json, terraform plan -lock=false) · bound 1/1");
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.depth).toBe("live+plan");
+  });
+
+  test("matches read at different depths name both", async () => {
+    setup(
+      { a: "plan", b: "state" },
+      [PLAN_NOTE],
+      {
+        a: { type: "Terraform::Resource", physicalId: "x", status: "OK", ownership: "owned" as const },
+        b: { type: "Terraform::Resource", physicalId: "y", status: "OK", ownership: "owned" as const },
+      },
+    );
+    entities.set("a", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} }));
+    entities.set("b", decl({ lexicon: "terraform", entityType: "Terraform::Resource", props: {} }));
+    try {
+      const doc = JSON.parse(await run(true));
+      expectValid(doc);
+      expect(doc.source).toMatchObject({ depth: "mixed", reads: ["plan", "state"] });
+      expect(doc.provenance).toContain("at the plan depth (terraform plan -lock=false) and from state");
+    } finally {
+      entities.delete("a");
+      entities.delete("b");
+    }
+  });
+
+  test("a plan read that fell back to state says so", async () => {
+    setup({ orders: "state" }, [STATE_NOTE], null, FELL_TO_STATE);
+    const text = await run();
+    expect(text).toContain("observed live · bound 1/1 · the plan read fell back to state");
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBe("state");
+    expect(doc.source.depth).toBeUndefined();
+  });
+
+  test("a live root's plan read that failed says live-plan answered alone", async () => {
+    const LIVE_NOTE = "terraform.roots.app: the plan read failed (the plan failed: x), so `live-plan -json` alone answered; plan attributes are absent";
+    setup({ orders: "live" }, [LIVE_NOTE], null, { "terraform.roots.app": { depth: "live+plan", fellBackTo: "live", reason: "plan-failed" } });
+    expect(await run()).toContain("observed live · bound 1/1 · the plan read fell back to live-plan alone");
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBe("live");
+    expect(doc.source.depth).toBeUndefined();
+  });
+
+  test("a live root whose plan read answered names both reads and no fallback", async () => {
+    setup({ orders: "live+plan" }, [PLAN_NOTE], null, { "terraform.roots.app": { depth: "live+plan" } });
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBeUndefined();
+    expect(doc.provenance).toBe("observed live and at the plan depth (live-plan -json, terraform plan -lock=false) · bound 1/1");
+  });
+
+  test("a live root whose live-plan failed reports no plan fallback", async () => {
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "terraform",
+        describeResources: async () => ({
+          observation: "v1" as const,
+          resources: {},
+          unobserved: { orders: { reason: "read-failed" as const, type: "Terraform::Resource" } },
+          sources: { orders: "live" },
+          notes: ["terraform.roots.app: no read answered (`live-plan -json` failed, so the plan read was not tried)"],
+        }),
+      }),
+    ]);
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBeUndefined();
+    expect(doc.provenance).not.toContain("fell back");
+  });
+
+  test("a plan read that fell back to declared says so", async () => {
+    setup(
+      { orders: "plan" },
+      [DECLARED_NOTE],
+      null,
+    );
+    loadPluginsMock.mockResolvedValue([
+      createMockPlugin({
+        name: "terraform",
+        describeResources: async () => ({
+          observation: "v1" as const,
+          resources: {},
+          unobserved: { orders: { reason: "no-binding" as const, type: "Terraform::Resource" } },
+          sources: { orders: "plan" },
+          notes: [DECLARED_NOTE],
+          rootReads: FELL_TO_DECLARED,
+        }),
+      }),
+    ]);
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBe("declared");
+    expect(doc.source.depth).toBeUndefined();
+    expect(doc.provenance).toContain("the plan read fell back to declared");
+  });
+
+  test("rewording the notes changes nothing: the fallback is read from the structured field", async () => {
+    setup({ orders: "state" }, ["the app root: plan unavailable, state used instead"], null, FELL_TO_STATE);
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBe("state");
+    expect(doc.provenance).toBe("observed live · bound 1/1 · the plan read fell back to state");
+  });
+
+  test("a note that reads like a fallback does not make one", async () => {
+    setup({ orders: "state" }, [STATE_NOTE, DECLARED_NOTE]);
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source.planFellBackTo).toBeUndefined();
+    expect(doc.provenance).toBe("observed live · bound 1/1");
+  });
+
+  test("a plain live or state answer is unchanged", async () => {
+    setup({ orders: "state" }, []);
+    expect(await run()).toContain("observed live · bound 1/1");
+    expect(await run()).not.toContain("plan");
+    const doc = JSON.parse(await run(true));
+    expectValid(doc);
+    expect(doc.source).toEqual({ kind: "live", env: "dev" });
+  });
+});

package/src/cli/handlers/search-paths.test.ts

@@ -0,0 +1,235 @@
+import { describe, test, expect, vi } from "vitest";
+import { __searchInternals, resolveKindTerms } from "./search";
+
+// #4359: transitive edges, attribute-qualified edges, and the path a match was reached by.
+const { parseQuery, matchTerm, findPath, formatPath, searchJson, explain, describeTerm } = __searchInternals;
+
+function node(id: string, kind: string, attrs: Record<string, unknown> = {}) {
+  return { id, kind, lexicon: "terraform", attrs } as never;
+}
+
+type G = { nodes: { id: string }[]; edges: unknown[] };
+
+function run(ir: G, query: string): string[] {
+  const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+  const terms = parseQuery(query);
+  // As runSearch does: `kind:aws_vpc` means aws_vpc, not aws_vpc_ipam_pool.
+  resolveKindTerms(terms, ir.nodes as never);
+  return ir.nodes
+    .filter((n) => terms.every((t) => matchTerm(n as never, t, ir as never, byId as never)))
+    .map((n) => n.id);
+}
+
+// Four resources linked by references, the way the terraform lexicon records
+// them: each edge points from the consumer to the producer, with the
+// consumer's attribute (viaAttr) and the producer's (toAttr).
+const chain: G = {
+  nodes: [
+    node("aws_instance.web", "aws_instance"),
+    node("aws_subnet.a", "aws_subnet"),
+    node("aws_vpc.main", "aws_vpc"),
+    node("aws_vpc_ipam_pool.p", "aws_vpc_ipam_pool"),
+  ],
+  edges: [
+    { from: "aws_instance.web", to: "aws_subnet.a", kind: "ref", viaAttr: "subnet_id", toAttr: "id" },
+    { from: "aws_subnet.a", to: "aws_vpc.main", kind: "ref", viaAttr: "vpc_id", toAttr: "id" },
+    { from: "aws_vpc.main", to: "aws_vpc_ipam_pool.p", kind: "ref", viaAttr: "ipv4_ipam_pool_id", toAttr: "id" },
+  ],
+};
+
+describe("edge term grammar", () => {
+  test("depth: * is one or more hops, {n} exactly n, {m,n} a range, {m,} open", () => {
+    expect(parseQuery("->*kind:aws_vpc")).toEqual([
+      { kind: "edge", a: "", dir: "out", depth: { min: 1, max: Infinity }, sub: { kind: "kind", a: "aws_vpc" } },
+    ]);
+    expect(parseQuery("<-{1,3}kind:aws_instance")[0]).toMatchObject({ dir: "in", depth: { min: 1, max: 3 } });
+    expect(parseQuery("<-{2}kind:aws_instance")[0]).toMatchObject({ depth: { min: 2, max: 2 } });
+    expect(parseQuery("<-{2,}kind:aws_instance")[0]).toMatchObject({ depth: { min: 2, max: Infinity } });
+  });
+
+  test("attribute qualifiers, with or without a target", () => {
+    expect(parseQuery("<-[via=vpc_id]kind:aws_subnet")).toEqual([
+      { kind: "edge", a: "", dir: "in", viaAttr: "vpc_id", sub: { kind: "kind", a: "aws_subnet" } },
+    ]);
+    expect(parseQuery("->*[via=subnet_id,to=id]")).toEqual([
+      { kind: "edge", a: "", dir: "out", depth: { min: 1, max: Infinity }, viaAttr: "subnet_id", toAttr: "id" },
+    ]);
+    expect(parseQuery("!->[to=arn]")[0]).toMatchObject({ negated: true, toAttr: "arn" });
+  });
+
+  test("a plain one-hop term parses exactly as before: no depth, no qualifier", () => {
+    expect(parseQuery("->kind:Subnet")).toEqual([{ kind: "edge", a: "", dir: "out", sub: { kind: "kind", a: "Subnet" } }]);
+    expect(Object.keys(parseQuery("<-kind:Instance")[0]).sort()).toEqual(["a", "dir", "kind", "sub"]);
+  });
+
+  test("what the grammar cannot read is refused with the correction", () => {
+    expect(() => parseQuery("->*")).toThrow(/needs a target/);
+    expect(() => parseQuery("!<-{1,2}")).toThrow(/needs a target/);
+    expect(() => parseQuery("->{0}kind:X")).toThrow(/depth/);
+    expect(() => parseQuery("->{3,1}kind:X")).toThrow(/depth/);
+    expect(() => parseQuery("->{a}kind:X")).toThrow(/depth/);
+    expect(() => parseQuery("->[from=x]kind:X")).toThrow(/qualifier/);
+    expect(() => parseQuery("->[via=x")).toThrow(/qualifier/);
+  });
+
+  test("describeTerm writes the operator back as the query spelled it", () => {
+    expect(describeTerm(parseQuery("->*kind:aws_vpc")[0] as never)).toBe("→*kind:aws_vpc (no such edge)");
+    expect(describeTerm(parseQuery("<-{1,3}[via=vpc_id]kind:aws_subnet")[0] as never)).toBe(
+      "←{1,3}[via=vpc_id]kind:aws_subnet (no such edge)",
+    );
+    expect(describeTerm(parseQuery("!->{2,}[to=id]")[0] as never)).toBe("!→{2,}[to=id] (no such edge)");
+  });
+});
+
+describe("transitive edges on a four-resource chain", () => {
+  test("a transitive term matches every node at any depth", () => {
+    expect(run(chain, "->*kind:aws_vpc_ipam_pool")).toEqual(["aws_instance.web", "aws_subnet.a", "aws_vpc.main"]);
+    expect(run(chain, "<-*kind:aws_instance")).toEqual(["aws_subnet.a", "aws_vpc.main", "aws_vpc_ipam_pool.p"]);
+  });
+
+  test("a bounded term matches only within its limit", () => {
+    expect(run(chain, "->{1,2}kind:aws_vpc_ipam_pool")).toEqual(["aws_subnet.a", "aws_vpc.main"]);
+    expect(run(chain, "->{3}kind:aws_vpc_ipam_pool")).toEqual(["aws_instance.web"]);
+    expect(run(chain, "->{2,}kind:aws_vpc_ipam_pool")).toEqual(["aws_instance.web", "aws_subnet.a"]);
+    expect(run(chain, "<-{1,2}kind:aws_instance")).toEqual(["aws_subnet.a", "aws_vpc.main"]);
+  });
+
+  test("one hop still means one hop", () => {
+    expect(run(chain, "->kind:aws_vpc_ipam_pool")).toEqual(["aws_vpc.main"]);
+    expect(run(chain, "!<-kind:aws_subnet kind:aws_vpc")).toEqual([]);
+  });
+});
+
+describe("attribute-qualified edges", () => {
+  test("[via=] matches only edges whose viaAttr is the given name", () => {
+    expect(run(chain, "<-[via=vpc_id]")).toEqual(["aws_vpc.main"]);
+    expect(run(chain, "->[via=vpc_id]kind:aws_vpc")).toEqual(["aws_subnet.a"]);
+    expect(run(chain, "->[via=subnet_id]kind:aws_vpc")).toEqual([]);
+  });
+
+  test("[to=] matches only edges whose toAttr is the given name", () => {
+    expect(run(chain, "->[to=id]")).toEqual(["aws_instance.web", "aws_subnet.a", "aws_vpc.main"]);
+    expect(run(chain, "->[to=arn]")).toEqual([]);
+  });
+
+  test("a qualifier holds for every edge on a transitive path", () => {
+    // web reaches the VPC through subnet_id then vpc_id, so no single name covers the path.
+    expect(run(chain, "->*[via=subnet_id]kind:aws_vpc")).toEqual([]);
+    expect(run(chain, "->*[to=id]kind:aws_vpc")).toEqual(["aws_instance.web", "aws_subnet.a"]);
+  });
+
+  test("an edge with no recorded attribute never satisfies a qualifier", () => {
+    const g: G = {
+      nodes: [node("x", "aws_instance"), node("y", "aws_subnet")],
+      edges: [{ from: "x", to: "y", kind: "ref" }],
+    };
+    expect(run(g, "->kind:aws_subnet")).toEqual(["x"]);
+    expect(run(g, "->[via=subnet_id]kind:aws_subnet")).toEqual([]);
+  });
+});
+
+describe("cycles", () => {
+  // a -> b -> c -> a, plus c -> d
+  const cyc: G = {
+    nodes: [node("a", "T::A"), node("b", "T::B"), node("c", "T::C"), node("d", "T::D")],
+    edges: [
+      { from: "a", to: "b", kind: "ref", viaAttr: "next" },
+      { from: "b", to: "c", kind: "ref", viaAttr: "next" },
+      { from: "c", to: "a", kind: "ref", viaAttr: "next" },
+      { from: "c", to: "d", kind: "ref", viaAttr: "sink" },
+    ],
+  };
+
+  test("a cycle does not hang the matcher, and a miss is a clean miss", () => {
+    expect(run(cyc, "->*kind:Nothing")).toEqual([]);
+    expect(run(cyc, "<-*kind:Nothing")).toEqual([]);
+    expect(run(cyc, "->{50,}kind:Nothing")).toEqual([]);
+  });
+
+  test("a walk round the cycle still finds what it should", () => {
+    // Every node of the cycle reaches d, and reaches itself.
+    expect(run(cyc, "->*kind:T::D")).toEqual(["a", "b", "c"]);
+    expect(run(cyc, "->*kind:T::A")).toEqual(["a", "b", "c"]);
+    // A depth past the cycle's length is reached by going round again.
+    expect(run(cyc, "->{4}kind:T::B")).toEqual(["a"]);
+    expect(run(cyc, "->{7,}kind:T::B")).toEqual(["a", "b", "c"]);
+  });
+});
+
+describe("the path each match was reached by", () => {
+  const byId = new Map(chain.nodes.map((n) => [n.id, n]));
+
+  test("findPath returns the hops in walk order, each in the edge's own direction", () => {
+    const [t] = parseQuery("->*kind:aws_vpc_ipam_pool");
+    const hops = findPath(chain.nodes[0] as never, t, chain as never, byId as never);
+    expect(hops).toEqual([
+      { from: "aws_instance.web", fromAttr: "subnet_id", to: "aws_subnet.a", toAttr: "id" },
+      { from: "aws_subnet.a", fromAttr: "vpc_id", to: "aws_vpc.main", toAttr: "id" },
+      { from: "aws_vpc.main", fromAttr: "ipv4_ipam_pool_id", to: "aws_vpc_ipam_pool.p", toAttr: "id" },
+    ]);
+    expect(formatPath(hops!, "out")).toBe(
+      "aws_instance.web.subnet_id -> aws_subnet.a.id; aws_subnet.a.vpc_id -> aws_vpc.main.id; aws_vpc.main.ipv4_ipam_pool_id -> aws_vpc_ipam_pool.p.id",
+    );
+  });
+
+  test("walking <- reads producer to consumer", () => {
+    const [t] = parseQuery("<-*kind:aws_instance");
+    const hops = findPath(chain.nodes[2] as never, t, chain as never, byId as never);
+    expect(formatPath(hops!, "in")).toBe("aws_vpc.main.id <- aws_subnet.a.vpc_id; aws_subnet.a.id <- aws_instance.web.subnet_id");
+  });
+
+  test("the path is the shortest one", () => {
+    const g: G = {
+      nodes: [node("x", "A"), node("y", "B"), node("z", "C")],
+      edges: [
+        { from: "x", to: "y", kind: "ref", viaAttr: "long" },
+        { from: "y", to: "z", kind: "ref", viaAttr: "long" },
+        { from: "x", to: "z", kind: "ref", viaAttr: "short" },
+      ],
+    };
+    const [t] = parseQuery("->*kind:C");
+    const hops = findPath(g.nodes[0] as never, t, g as never, new Map(g.nodes.map((n) => [n.id, n])) as never);
+    expect(hops).toEqual([{ from: "x", fromAttr: "short", to: "z" }]);
+  });
+
+  test("--explain prints one path line per match and edge term", () => {
+    const query = "kind:aws_instance ->*kind:aws_vpc_ipam_pool";
+    const terms = parseQuery(query);
+    const matches = [chain.nodes[0]];
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((s: string) => { lines.push(s); });
+    explain(terms as never, matches as never, chain as never, byId as never, query);
+    spy.mockRestore();
+    expect(lines[0]).toContain("1 of 1 aws_instance matched");
+    expect(lines).toContain(
+      "  path aws_instance.web.subnet_id -> aws_subnet.a.id; aws_subnet.a.vpc_id -> aws_vpc.main.id; aws_vpc.main.ipv4_ipam_pool_id -> aws_vpc_ipam_pool.p.id",
+    );
+  });
+
+  test("--json carries the path as a list of hops per edge term", () => {
+    const query = "->{1,2}[to=id]kind:aws_vpc_ipam_pool !<-kind:aws_instance";
+    const terms = parseQuery(query);
+    const matches = [chain.nodes[2]];
+    const out = searchJson(query, { kind: "declared" }, matches as never, terms, chain as never, byId as never);
+    expect(out).toEqual({
+      query,
+      source: { kind: "declared" },
+      matches: [
+        {
+          id: "aws_vpc.main",
+          displayId: "aws_vpc.main",
+          kind: "aws_vpc",
+          paths: [
+            {
+              term: "->{1,2}[to=id]kind:aws_vpc_ipam_pool",
+              dir: "out",
+              hops: [{ from: "aws_vpc.main", fromAttr: "ipv4_ipam_pool_id", to: "aws_vpc_ipam_pool.p", toAttr: "id" }],
+            },
+          ],
+        },
+      ],
+    });
+    // A query with no edge term carries an empty path list.
+    expect(searchJson("kind:aws_vpc", { kind: "declared" }, matches as never, parseQuery("kind:aws_vpc"), chain as never, byId as never).matches[0].paths).toEqual([]);
+  });
+});