@intentius/chant 0.124.46 → 0.124.48

package/src/terraform/cuts.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { loadHcl2json, parseTerraformDir } from "./parse";
+import { closure, components, cuts } from "./cuts";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/**
+ * #3909: cuts and reference-closed sets. The proof runs against depth-estate
+ * (#2323) as `parseTerraformDir` builds it; several components, a cycle, a
+ * straddling output and cross-stack edges are on hand-built graphs.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const ends = (edges: TfEdge[]): string[] => edges.map((e) => `${e.from} -> ${e.to}`);
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+const DEPTH_ESTATE_BLOCKS = [
+  "aws_cloudwatch_log_group.api",
+  "aws_db_subnet_group.main",
+  "aws_kms_key.data",
+  "aws_lambda_function.api",
+  "aws_lb.public",
+  "aws_lb_listener.https",
+  "aws_lb_target_group.app",
+  "aws_rds_cluster.main",
+  "aws_rds_cluster_instance.one",
+  "aws_s3_bucket.assets",
+  "aws_s3_bucket_versioning.assets",
+  "aws_security_group.app",
+  "aws_security_group.db",
+  "aws_subnet.a",
+  "aws_subnet.b",
+  "aws_subnet.private",
+  "aws_vpc.main",
+  "module.platform",
+];
+
+describe("against depth-estate", () => {
+  test("components match the pinned list: one, with the module and the count hiding what it holds", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(components(graph)).toEqual([
+      {
+        resources: DEPTH_ESTATE_BLOCKS,
+        outputs: ["output.db_endpoint", "output.lb_dns"],
+        instances: "unknown",
+        hiddenBy: ["aws_subnet.private", "module.platform"],
+      },
+    ]);
+  });
+
+  test("cuts of a hand-picked set name each crossing edge with its direction", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = cuts(graph, ["aws_rds_cluster.main", "aws_rds_cluster_instance.one"]);
+    expect(ends(c.inbound)).toEqual([
+      "aws_lambda_function.api -> aws_rds_cluster.main",
+      "output.db_endpoint -> aws_rds_cluster.main",
+    ]);
+    expect(ends(c.outbound)).toEqual([
+      "aws_rds_cluster.main -> aws_db_subnet_group.main",
+      "aws_rds_cluster.main -> aws_kms_key.data",
+      "aws_rds_cluster.main -> aws_security_group.db",
+    ]);
+    expect(c.counts).toEqual({
+      inbound: { resources: 1, outputs: 1, crossStack: 0 },
+      outbound: { resources: 3, outputs: 0, crossStack: 0 },
+    });
+    expect(c.bothWays).toBe(true);
+  });
+
+  test("closure from a leaf with outbound allowed leaves only outbound cuts", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const leaf = closure(graph, ["aws_rds_cluster_instance.one"], "outbound");
+    expect(leaf.resources).toEqual(["aws_rds_cluster_instance.one"]);
+    expect(leaf.inbound).toEqual([]);
+    expect(ends(leaf.outbound)).toEqual(["aws_rds_cluster_instance.one -> aws_rds_cluster.main"]);
+
+    // A seed with dependents takes them all, outputs included.
+    const key = closure(graph, ["aws_kms_key.data"], "outbound");
+    expect(key.resources).toEqual(["aws_kms_key.data", "aws_lambda_function.api", "aws_rds_cluster.main", "aws_rds_cluster_instance.one"]);
+    expect(key.outputs).toEqual(["output.db_endpoint"]);
+    expect(key.inbound).toEqual([]);
+    expect(key.outbound.length).toBeGreaterThan(0);
+    expect(key.instances).toBe(4);
+  });
+
+  test("closure with inbound allowed takes what the seed depends on, and leaves only inbound cuts", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = closure(graph, ["aws_rds_cluster_instance.one"], "inbound");
+    expect(c.outbound).toEqual([]);
+    expect(c.resources).toContain("aws_vpc.main");
+    expect(c.inbound.every((e) => !c.resources.includes(e.from))).toBe(true);
+  });
+
+  test("closure with none allowed returns the leaf's whole component", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const c = closure(graph, ["aws_rds_cluster_instance.one"], "none");
+    expect(c.resources).toEqual(DEPTH_ESTATE_BLOCKS);
+    expect(c.outputs).toEqual(["output.db_endpoint", "output.lb_dns"]);
+    expect([...c.inbound, ...c.outbound]).toEqual([]);
+    expect(c.instances).toBe("unknown");
+  });
+
+  test("a set that splits a fold is contracted before its cuts are counted", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const child = cuts(graph, ["aws_s3_bucket_versioning.assets"]);
+    const parent = cuts(graph, ["aws_s3_bucket.assets"]);
+    expect(child).toEqual(parent);
+    expect(parent.resources).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+    expect(ends(parent.inbound)).toEqual(["aws_lambda_function.api -> aws_s3_bucket.assets"]);
+    expect(parent.outbound).toEqual([]);
+  });
+});
+
+describe("on hand-built graphs", () => {
+  test("separate components stay separate, and an output never joins them", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sns_topic.c")],
+      edges: [
+        edge("aws_sqs_queue.b", "aws_sqs_queue.a"),
+        edge("output.both", "aws_sqs_queue.a", { fromKind: "output" }),
+        edge("output.both", "aws_sns_topic.c", { fromKind: "output" }),
+      ],
+    };
+    expect(components(graph)).toEqual([
+      { resources: ["aws_sns_topic.c"], outputs: ["output.both"], instances: 1 },
+      { resources: ["aws_sqs_queue.a", "aws_sqs_queue.b"], outputs: ["output.both"], instances: 2 },
+    ]);
+    // The straddling output stays outside a none-closure, its read left as a cut.
+    const c = closure(graph, ["aws_sqs_queue.a"], "none");
+    expect(c.outputs).toEqual([]);
+    expect(ends(c.inbound)).toEqual(["output.both -> aws_sqs_queue.a"]);
+  });
+
+  test("a depends_on cycle terminates in every closure", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sqs_queue.c")],
+      edges: [edge("aws_sqs_queue.a", "aws_sqs_queue.b"), edge("aws_sqs_queue.b", "aws_sqs_queue.c"), edge("aws_sqs_queue.c", "aws_sqs_queue.a")],
+    };
+    for (const allow of ["inbound", "outbound", "none"] as const) {
+      expect(closure(graph, ["aws_sqs_queue.a"], allow).resources).toEqual(["aws_sqs_queue.a", "aws_sqs_queue.b", "aws_sqs_queue.c"]);
+    }
+  });
+
+  test("crossStack cuts are counted apart", () => {
+    const graph: TfGraph = {
+      nodes: [node("Data/Bucket"), node("App/Fn")],
+      edges: [edge("App/Fn", "Data/Bucket", { crossStack: true })],
+    };
+    expect(cuts(graph, ["Data/Bucket"]).counts.inbound).toEqual({ resources: 1, outputs: 0, crossStack: 1 });
+  });
+
+  test("an address the graph does not hold is an error", () => {
+    expect(() => cuts({ nodes: [], edges: [] }, ["aws_vpc.nope"])).toThrow(/not a resource, module or output/);
+  });
+});

package/src/terraform/cuts.ts

@@ -0,0 +1,188 @@
+/**
+ * Cuts and reference-closed sets over the carve graph (#3909).
+ *
+ * `carve advise` scores one block at a time. A consumer splitting one root into
+ * several (terragucci's estate carving) needs the same question for a set:
+ * which edges cross its boundary and which way, and the smallest set around a
+ * seed whose crossings all run a way the caller allows. These are pure
+ * functions over `TfGraph`, on the index and walk in `reach.ts`, so the rules
+ * there hold here too: folds contract first, outputs are terminal and counted
+ * apart, modules and unresolved `count` are named as hiding their contents, a
+ * `depends_on` cycle terminates, and `crossStack` edges are counted apart.
+ *
+ * Nothing here ranks sets, reads state or plan times, writes HCL, or knows
+ * about roots or backends; that stays with the consumer.
+ */
+
+import { carveIndex, cmp, hidesContents, isOutputAddress, walkFrom, weigh, type CarveIndex } from "./reach";
+import type { TfEdge, TfGraph } from "./types";
+
+/** Cut edges of one direction, counted. */
+export interface CutCount {
+  /** Edges whose reading side is a resource or module block. */
+  resources: number;
+  /** Edges whose reading side is an `output` block. */
+  outputs: number;
+  /** Of all of them, the `crossStack` edges (a CDK `Fn::ImportValue`). */
+  crossStack: number;
+}
+
+/** A set of blocks, as the walks see it. */
+export interface BlockSet {
+  /** Resource and module addresses, each fold parent with the blocks folded into it. Sorted. */
+  resources: string[];
+  /** `output.<name>` pseudo-addresses in the set. Sorted. */
+  outputs: string[];
+}
+
+export interface Cuts extends BlockSet {
+  /** Edges where something outside reads something inside, as the graph holds them. */
+  inbound: TfEdge[];
+  /** Edges where something inside reads something outside. */
+  outbound: TfEdge[];
+  counts: { inbound: CutCount; outbound: CutCount };
+  /** Cuts run in both directions: the set can move only with wiring both ways. */
+  bothWays: boolean;
+}
+
+/** The cut directions a closure may leave: `inbound` (outside may read in), `outbound` (inside may read out), or `none`. */
+export type CutAllowance = "inbound" | "outbound" | "none";
+
+export interface Closure extends Cuts {
+  /** The seeds as the walk saw them, folds contracted. */
+  seeds: string[];
+  allow: CutAllowance;
+  /**
+   * How many resource instances the set stands for: each block once, or its
+   * instance count once `--state` resolved it. `"unknown"` where a module or an
+   * unresolved `count`/`for_each` hides how much it holds; `hiddenBy` names them.
+   */
+  instances: number | "unknown";
+  hiddenBy?: string[];
+}
+
+export interface Component extends BlockSet {
+  /** As {@link Closure.instances}. */
+  instances: number | "unknown";
+  hiddenBy?: string[];
+}
+
+/**
+ * The graph's weakly connected components (#3909): blocks joined by a
+ * reference either way, fold-contracted, each module one node. An output never
+ * joins two components, since outputs are terminal; it is listed in every
+ * component it reads into. Components are sorted by their first address.
+ */
+export function components(graph: TfGraph): Component[] {
+  const index = carveIndex(graph);
+  const assigned = new Set<string>();
+  const found: Component[] = [];
+  for (const address of [...index.nodes.keys()].sort(cmp)) {
+    const start = index.rep(address);
+    if (assigned.has(start)) continue;
+    const reached = walkFrom(index, [start], "both");
+    const reps = [start, ...[...reached.keys()].filter((a) => !isOutputAddress(a))];
+    for (const rep of reps) assigned.add(rep);
+    found.push({ ...blockSet(index, reps, [...reached.keys()].filter(isOutputAddress)), ...holdings(index, reps) });
+  }
+  return found;
+}
+
+/**
+ * Every edge crossing the boundary of `addresses` (#3909). A folded block in
+ * the set brings its parent and siblings, and a fold parent its folded blocks,
+ * before anything is counted, so an edge inside one fold is never a cut. An
+ * `output.<name>` in the set is inside it like any block.
+ *
+ * Throws when an address is not a block of the graph.
+ */
+export function cuts(graph: TfGraph, addresses: Iterable<string>): Cuts {
+  const index = carveIndex(graph);
+  return cutsOf(index, contract(index, addresses));
+}
+
+/**
+ * The smallest superset of `seeds` whose remaining cuts all run in the
+ * direction `allow` permits, plus those cuts (#3909).
+ *
+ *  - `outbound`: nothing outside may read in, so the set takes every
+ *    dependent of the seeds, outputs included.
+ *  - `inbound`: nothing inside may read out, so the set takes everything the
+ *    seeds depend on.
+ *  - `none`: the seeds' whole components, with each output that reads only
+ *    into them.
+ *
+ * Outputs are terminal, so none of these walks passes through one. An output
+ * that reads both the set and something outside it is therefore a cut no
+ * closure removes: under `none` it stays outside and its read into the set is
+ * left as an inbound cut, for the caller to wire.
+ */
+export function closure(graph: TfGraph, seeds: Iterable<string>, allow: CutAllowance): Closure {
+  const index = carveIndex(graph);
+  const start = contract(index, seeds);
+  const direction = allow === "outbound" ? "in" : allow === "inbound" ? "out" : "both";
+  const members = new Set([...start, ...walkFrom(index, start, direction).keys()]);
+  if (allow === "none") {
+    for (const address of [...members]) {
+      if (!isOutputAddress(address) || start.has(address)) continue;
+      const reads = (index.adj.out.get(address) ?? []).map((e) => e.to);
+      if (!reads.every((to) => members.has(to))) members.delete(address);
+    }
+  }
+  const found = cutsOf(index, members);
+  return {
+    ...found,
+    seeds: [...start].sort(cmp),
+    allow,
+    ...holdings(index, [...members].filter((a) => !isOutputAddress(a))),
+  };
+}
+
+/** The addresses as the walks see them: each fold child replaced by its parent. Throws on an unknown address. */
+function contract(index: CarveIndex, addresses: Iterable<string>): Set<string> {
+  const out = new Set<string>();
+  for (const address of addresses) {
+    const known = index.nodes.has(address) || (isOutputAddress(address) && index.adj.out.has(address));
+    if (!known) throw new Error(`carve: ${address} is not a resource, module or output in this graph`);
+    out.add(index.rep(address));
+  }
+  return out;
+}
+
+function cutsOf(index: CarveIndex, members: ReadonlySet<string>): Cuts {
+  const inbound: TfEdge[] = [];
+  const outbound: TfEdge[] = [];
+  for (const address of members) {
+    for (const e of index.adj.in.get(address) ?? []) if (!members.has(e.from)) inbound.push(e.edge);
+    for (const e of index.adj.out.get(address) ?? []) if (!members.has(e.to)) outbound.push(e.edge);
+  }
+  const byEnds = (a: TfEdge, b: TfEdge): number => cmp(a.from, b.from) || cmp(a.to, b.to);
+  inbound.sort(byEnds);
+  outbound.sort(byEnds);
+  const reps = [...members];
+  return {
+    ...blockSet(index, reps.filter((a) => !isOutputAddress(a)), reps.filter(isOutputAddress)),
+    inbound,
+    outbound,
+    counts: { inbound: countOf(inbound), outbound: countOf(outbound) },
+    bothWays: inbound.length > 0 && outbound.length > 0,
+  };
+}
+
+function countOf(edges: readonly TfEdge[]): CutCount {
+  const outputs = edges.filter((e) => e.fromKind === "output").length;
+  return { resources: edges.length - outputs, outputs, crossStack: edges.filter((e) => e.crossStack).length };
+}
+
+function blockSet(index: CarveIndex, reps: readonly string[], outputs: readonly string[]): BlockSet {
+  return {
+    resources: reps.flatMap((rep) => index.membersOf(rep)).sort(cmp),
+    outputs: [...outputs].sort(cmp),
+  };
+}
+
+function holdings(index: CarveIndex, reps: readonly string[]): { instances: number | "unknown"; hiddenBy?: string[] } {
+  const instances = weigh(index, reps);
+  if (instances !== "unknown") return { instances };
+  return { instances, hiddenBy: reps.filter((a) => hidesContents(index.nodes.get(a)!)).sort(cmp) };
+}

package/src/terraform/folds.ts

@@ -0,0 +1,44 @@
+/**
+ * Fold detection for the carve graph, shared by the scorer and the walks.
+ *
+ * A sub-resource whose type inlines into a parent (`foldParentOf`) carves with
+ * that parent when the parent is in the estate under the same name:
+ * `aws_s3_bucket_versioning.assets` goes with `aws_s3_bucket.assets`. The
+ * scorer drops it from the ranking and discounts its edge to the parent; the
+ * walks in `reach.ts` contract it into the parent before stepping, since an
+ * uncontracted walk counts the child as a separate dependent (#2325 measured a
+ * 100% overstatement on the sample estate). It lived privately in `score.ts`
+ * until the walks needed it.
+ */
+
+import { foldParentOf } from "./tier-map";
+import type { TfGraph } from "./types";
+
+export interface Folds {
+  /** Every address that folds into a parent present in the estate. */
+  folded: Set<string>;
+  /** Parent address → the addresses folded into it. */
+  childrenOf: Map<string, Set<string>>;
+}
+
+/**
+ * Build the set of addresses that fold into a parent present in the estate, plus
+ * the reverse lookup (parent → its folded children), so a parent can discount
+ * inbound edges coming from its own folded sub-resources.
+ */
+export function computeFolds(graph: TfGraph): Folds {
+  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+  const folded = new Set<string>();
+  const childrenOf = new Map<string, Set<string>>();
+  for (const node of graph.nodes) {
+    if (node.kind !== "resource" || !node.type) continue;
+    const parentType = foldParentOf(node.type);
+    if (!parentType) continue;
+    const parentAddress = `${parentType}.${node.name}`;
+    if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
+    folded.add(node.address);
+    if (!childrenOf.has(parentAddress)) childrenOf.set(parentAddress, new Set());
+    childrenOf.get(parentAddress)!.add(node.address);
+  }
+  return { folded, childrenOf };
+}

package/src/terraform/graph.ts

@@ -270,6 +270,13 @@ function blockHasMeta(block: unknown, key: string): boolean {
   return !!block && typeof block === "object" && key in (block as Record<string, unknown>);
 }
 
+/** Which expansion meta-argument a block carries, as a spreadable `TfNode` field (#2325). */
+function expansionOf(block: unknown): { expansion?: "count" | "for_each" } {
+  if (blockHasMeta(block, "count")) return { expansion: "count" };
+  if (blockHasMeta(block, "for_each")) return { expansion: "for_each" };
+  return {};
+}
+
 /**
  * The literal string at a dotted path into a block, or undefined when the path
  * misses or lands on an interpolation. A dotted path walks nested blocks —
@@ -366,6 +373,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
         name,
         instances: 1,
         hasDynamic: dynamic || touchesData,
+        ...expansionOf(block),
         identity: literalIdentity(block, type),
         dataSourceValues: dataSourceValues(block, type),
       });
@@ -386,6 +394,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
       name,
       instances: 1,
       hasDynamic: dynamic || touchesData,
+      ...expansionOf(block),
     });
   }
 

package/src/terraform/radius.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { carveAdvise, carveJson, formatCarveReport } from "../cli/commands/carve";
+import { loadHcl2json } from "./parse";
+import { blastRadius } from "./reach";
+import { scoreEstate } from "./score";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/** #2326: blast radius on advise, its own axis beside the score. */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const STATE = join(ESTATE, "terraform.tfstate");
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+describe("radius on carve advise against depth-estate", () => {
+  test("each resource carries its radius in the JSON, and the score still sums from its penalties", async () => {
+    if (!parserAvailable) return;
+    const result = await carveAdvise({ from: ESTATE, statePath: STATE });
+    const byAddress = new Map(carveJson(result).resources.map((r) => [r.address, r]));
+    expect(byAddress.get("aws_db_subnet_group.main")?.radius).toEqual({ resources: 3, outputs: 1, depth: 2 });
+    expect(byAddress.get("aws_lambda_function.api")?.radius).toEqual({ resources: 0, outputs: 0, depth: 0 });
+    for (const r of byAddress.values()) {
+      if (r.breakdown.tier === null) continue;
+      const sum = 100 + Object.values(r.breakdown.penalties).reduce((a, b) => a + b, 0);
+      expect(r.score).toBe(Math.max(0, Math.min(100, sum)));
+    }
+  });
+
+  test("the subnet group outranks the cluster on peelability and out-reaches it on radius", async () => {
+    if (!parserAvailable) return;
+    const result = await carveAdvise({ from: ESTATE });
+    const group = result.results!.find((r) => r.address === "aws_db_subnet_group.main")!;
+    const cluster = result.results!.find((r) => r.address === "aws_rds_cluster.main")!;
+    expect(group.score).toBeGreaterThan(cluster.score);
+    expect(group.radius!.resources).toBeGreaterThan(cluster.radius!.resources as number);
+  });
+
+  test("a module or an unresolved count makes the resource count unknown, and says which", async () => {
+    if (!parserAvailable) return;
+    const bare = await carveAdvise({ from: ESTATE });
+    const vpc = bare.results!.find((r) => r.address === "aws_vpc.main")!;
+    expect(vpc.radius).toEqual({ resources: "unknown", outputs: 2, depth: 3, hiddenBy: ["aws_subnet.private", "module.platform"] });
+    const withState = await carveAdvise({ from: ESTATE, statePath: STATE });
+    expect(withState.results!.find((r) => r.address === "aws_vpc.main")!.radius!.hiddenBy).toEqual(["module.platform"]);
+  });
+
+  test("the human report prints the radius as a column", async () => {
+    if (!parserAvailable) return;
+    const text = formatCarveReport(await carveAdvise({ from: ESTATE }));
+    expect(text).toMatch(/ 80 {2}3\+1 d2 {2}aws_db_subnet_group\.main /);
+    expect(text).toMatch(/\?\+2 d3 {2}aws_vpc\.main /);
+    expect(text).toMatch(/ - {7}aws_lambda_function\.api /);
+    expect(text).toContain("Radius: resources+outputs");
+  });
+});
+
+describe("radius on hand-built graphs", () => {
+  test("instances weight the count once state resolved them, and only then", () => {
+    const graph = (resolved: boolean): TfGraph => ({
+      nodes: [
+        node("aws_vpc.main"),
+        node("aws_subnet.private", { expansion: "count", hasDynamic: true, instances: resolved ? 3 : 1, ...(resolved ? { instancesFrom: "state" as const } : {}) }),
+      ],
+      edges: [edge("aws_subnet.private", "aws_vpc.main")],
+    });
+    expect(blastRadius(graph(true), "aws_vpc.main")).toEqual({ resources: 3, outputs: 0, depth: 1 });
+    expect(blastRadius(graph(false), "aws_vpc.main")).toEqual({ resources: "unknown", outputs: 0, depth: 1, hiddenBy: ["aws_subnet.private"] });
+  });
+
+  test("on a graph with crossStack edges the radius splits off what sits across a stack boundary", () => {
+    const graph: TfGraph = {
+      nodes: [node("Data/Bucket"), node("Data/Reader"), node("App/Fn"), node("App/Alarm")],
+      edges: [edge("Data/Reader", "Data/Bucket"), edge("App/Fn", "Data/Bucket", { crossStack: true }), edge("App/Alarm", "App/Fn")],
+    };
+    const bucket = scoreEstate(graph, { tierOf: () => ({ tier: 1, mapsTo: "AWS::S3::Bucket" }) }).find((r) => r.address === "Data/Bucket")!;
+    expect(bucket.radius).toEqual({ resources: 3, outputs: 0, depth: 2, crossStack: 2 });
+  });
+});

package/src/terraform/reach.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { loadHcl2json, parseTerraformDir } from "./parse";
+import { carveIndex, reach } from "./reach";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/**
+ * #2325: transitive reachability over the carve graph. The fixture assertions
+ * run against depth-estate (#2323) as the production parse builds it; the
+ * cycle and cross-stack cases need graphs Terraform would not produce, so they
+ * are hand-built.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const STATE = join(ESTATE, "terraform.tfstate");
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+describe("reach against depth-estate", () => {
+  test("the subnet group's radius is the cluster, its instance and the Lambda, plus one output, two deep", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(reach(graph, "aws_db_subnet_group.main")).toEqual({
+      address: "aws_db_subnet_group.main",
+      resources: ["aws_lambda_function.api", "aws_rds_cluster.main", "aws_rds_cluster_instance.one"],
+      outputs: ["output.db_endpoint"],
+      depth: 2,
+      crossStack: [],
+      hidden: [],
+    });
+    const vpc = reach(graph, "aws_vpc.main");
+    expect(vpc.resources).toHaveLength(13);
+    expect(vpc.outputs).toEqual(["output.db_endpoint", "output.lb_dns"]);
+    expect(vpc.depth).toBe(3);
+  });
+
+  test("folds contract first: the bucket's radius is the Lambda alone, not its own versioning block", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    // The uncontracted graph has the versioning block reading the bucket.
+    expect(graph.edges.some((e) => e.from === "aws_s3_bucket_versioning.assets" && e.to === "aws_s3_bucket.assets")).toBe(true);
+    expect(reach(graph, "aws_s3_bucket.assets").resources).toEqual(["aws_lambda_function.api"]);
+    // Asking from the folded child walks from its parent.
+    expect(reach(graph, "aws_s3_bucket_versioning.assets").address).toBe("aws_s3_bucket.assets");
+    expect(carveIndex(graph).membersOf("aws_s3_bucket.assets")).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+  });
+
+  test("outputs are counted apart and end the walk", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const lb = reach(graph, "aws_lb.public");
+    expect(lb.resources).toEqual(["aws_lb_listener.https"]);
+    expect(lb.outputs).toEqual(["output.lb_dns"]);
+    expect(reach(graph, "aws_lb_listener.https")).toMatchObject({ resources: [], outputs: [], depth: 0 });
+  });
+
+  test("a module and an unresolved count are named as hiding their contents; --state resolves the count", async () => {
+    if (!parserAvailable) return;
+    const bare = await parseTerraformDir(ESTATE);
+    expect(reach(bare, "aws_vpc.main").hidden).toEqual(["aws_subnet.private", "module.platform"]);
+    const withState = await parseTerraformDir(ESTATE, { statePath: STATE });
+    expect(reach(withState, "aws_vpc.main").hidden).toEqual(["module.platform"]);
+  });
+
+  test("direction out walks what a node needs", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(reach(graph, "aws_rds_cluster_instance.one", { direction: "out" }).resources).toEqual([
+      "aws_db_subnet_group.main",
+      "aws_kms_key.data",
+      "aws_rds_cluster.main",
+      "aws_security_group.db",
+      "aws_subnet.a",
+      "aws_subnet.b",
+      "aws_vpc.main",
+    ]);
+  });
+});
+
+describe("reach on hand-built graphs", () => {
+  test("a depends_on cycle terminates and does not count the start", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sqs_queue.c")],
+      edges: [
+        edge("aws_sqs_queue.a", "aws_sqs_queue.b", { via: ["depends_on"] }),
+        edge("aws_sqs_queue.b", "aws_sqs_queue.c", { via: ["depends_on"] }),
+        edge("aws_sqs_queue.c", "aws_sqs_queue.a", { via: ["depends_on"] }),
+      ],
+    };
+    expect(reach(graph, "aws_sqs_queue.a")).toMatchObject({ resources: ["aws_sqs_queue.b", "aws_sqs_queue.c"], depth: 2 });
+  });
+
+  test("what is reachable only through a crossStack edge is listed apart", () => {
+    const graph: TfGraph = {
+      nodes: [node("A/Bucket"), node("A/Fn"), node("B/Fn"), node("B/Alarm")],
+      edges: [
+        edge("A/Fn", "A/Bucket"),
+        edge("B/Fn", "A/Bucket", { crossStack: true }),
+        edge("B/Alarm", "B/Fn"),
+      ],
+    };
+    expect(reach(graph, "A/Bucket")).toMatchObject({ resources: ["A/Fn", "B/Alarm", "B/Fn"], crossStack: ["B/Alarm", "B/Fn"] });
+  });
+
+  test("an address the graph does not hold is an error, not an empty radius", () => {
+    expect(() => reach({ nodes: [], edges: [] }, "aws_vpc.nope")).toThrow(/not a resource or module/);
+  });
+
+  test("under 100 ms at 6 000 nodes, index included", () => {
+    // Layered like the spike's synthetic estates: 60 layers of 100, each node
+    // reading two nodes in the layer below, about 11 800 edges. Node i reads
+    // 2i and 2i+1 below it, so the dependents of one bottom node double per
+    // layer and a walk from it covers almost everything.
+    const layers = 60;
+    const width = 100;
+    const nodes: TfNode[] = [];
+    const edges: TfEdge[] = [];
+    for (let l = 0; l < layers; l++) {
+      for (let i = 0; i < width; i++) {
+        nodes.push(node(`aws_sqs_queue.l${l}_${i}`));
+        if (l > 0) {
+          edges.push(edge(`aws_sqs_queue.l${l}_${i}`, `aws_sqs_queue.l${l - 1}_${(2 * i) % width}`));
+          edges.push(edge(`aws_sqs_queue.l${l}_${i}`, `aws_sqs_queue.l${l - 1}_${(2 * i + 1) % width}`));
+        }
+      }
+    }
+    reach({ nodes, edges }, "aws_sqs_queue.l0_0"); // warm the JIT on a different graph object
+    const graph: TfGraph = { nodes, edges };
+    const started = performance.now();
+    const r = reach(graph, "aws_sqs_queue.l0_0");
+    const took = performance.now() - started;
+    expect(r.resources.length).toBeGreaterThan(5_000);
+    expect(took).toBeLessThan(100);
+  });
+});