@intentius/chant 0.61.0 → 0.63.0

package/src/terraform/graph.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { inboundEdges, outboundEdges, refFromAccessor } from "./graph";
+import { collectExpressions, inboundEdges, outboundEdges, refFromAccessor } from "./graph";
 import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import type { Hcl2JsonTree } from "./types";
 
@@ -214,6 +214,153 @@ describe("buildGraph", () => {
   });
 });
 
+/**
+ * References that reach a resource through a `locals` or `data` block (#2324).
+ * Neither is a node, both are load-bearing for the plan: the estate below is
+ * the one the blast-radius spike measured, where one bucket has three
+ * dependents by three routes and the advisor used to report one.
+ */
+describe("references through locals and data blocks", () => {
+  const threeRoutes: Hcl2JsonTree = {
+    resource: {
+      aws_s3_bucket: { assets: [{ bucket: "app-assets" }] },
+      aws_lambda_function: {
+        via_local: [{ environment: { variables: { B: "${local.assets_id}" } } }],
+        via_data: [{ environment: { variables: { B: "${data.aws_s3_bucket.lookup.arn}" } } }],
+        direct: [{ environment: { variables: { B: "${aws_s3_bucket.assets.arn}" } } }],
+      },
+    },
+    locals: [{ assets_id: "${aws_s3_bucket.assets.id}" }],
+    data: { aws_s3_bucket: { lookup: [{ bucket: "${aws_s3_bucket.assets.bucket}" }] } },
+  };
+
+  test("all three routes to one bucket are inbound edges", () => {
+    const g = buildFixtureGraph(threeRoutes);
+    expect(inboundEdges(g, "aws_s3_bucket.assets")).toEqual([
+      { from: "aws_lambda_function.direct", to: "aws_s3_bucket.assets", attrs: ["arn"], via: ["environment"] },
+      { from: "aws_lambda_function.via_data", to: "aws_s3_bucket.assets", attrs: ["bucket"], via: ["environment"] },
+      { from: "aws_lambda_function.via_local", to: "aws_s3_bucket.assets", attrs: ["id"], via: ["environment"] },
+    ]);
+    // The referrers stay off the node list: nothing carves a local or a data source.
+    expect(g.nodes.map((n) => n.address).filter((a) => a.startsWith("local.") || a.startsWith("data."))).toEqual([]);
+  });
+
+  test("each dependent gets the outbound edge to match", () => {
+    const g = buildFixtureGraph(threeRoutes);
+    for (const from of ["aws_lambda_function.direct", "aws_lambda_function.via_data", "aws_lambda_function.via_local"]) {
+      expect(outboundEdges(g, from).map((e) => e.to)).toEqual(["aws_s3_bucket.assets"]);
+    }
+  });
+
+  test("reading a data source still marks the reader dynamic", () => {
+    const g = buildFixtureGraph(threeRoutes);
+    const byAddress = Object.fromEntries(g.nodes.map((n) => [n.address, n]));
+    expect(byAddress["aws_lambda_function.via_data"].hasDynamic).toBe(true);
+    expect(byAddress["aws_lambda_function.via_local"].hasDynamic).toBe(false);
+  });
+
+  test("a chain of locals resolves to the resource the chain ultimately names", () => {
+    const g = buildFixtureGraph({
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "app-assets" }] },
+        aws_lambda_function: { api: [{ environment: { variables: { B: "${local.c}" } } }] },
+      },
+      locals: [{ a: "${aws_s3_bucket.assets.id}" }, { b: "${local.a}", c: "${local.b}" }],
+    });
+    expect(inboundEdges(g, "aws_s3_bucket.assets")).toEqual([
+      { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["id"], via: ["environment"] },
+    ]);
+  });
+
+  test("a data source reading a local reading a data source resolves through both", () => {
+    const g = buildFixtureGraph({
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "app-assets" }] },
+        aws_lambda_function: { api: [{ environment: { variables: { B: "${data.aws_s3_bucket.outer.arn}" } } }] },
+      },
+      locals: [{ inner_name: "${data.aws_s3_bucket.inner.id}" }],
+      data: {
+        aws_s3_bucket: {
+          inner: [{ bucket: "${aws_s3_bucket.assets.bucket}" }],
+          outer: [{ bucket: "${local.inner_name}" }],
+        },
+      },
+    });
+    expect(inboundEdges(g, "aws_s3_bucket.assets").map((e) => e.from)).toEqual(["aws_lambda_function.api"]);
+  });
+
+  test("a self-referential or mutually recursive local resolves without hanging", () => {
+    // Terraform rejects both of these; the advisor only reads an estate, so it
+    // has to reach a fixpoint on one rather than recurse forever.
+    const g = buildFixtureGraph({
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "app-assets" }] },
+        aws_lambda_function: {
+          selfish: [{ environment: { variables: { B: "${local.me}" } } }],
+          looper: [{ environment: { variables: { B: "${local.x}" } } }],
+        },
+      },
+      locals: [
+        { me: "${local.me}" },
+        { x: "${local.y}", y: "${local.x}" },
+        { grounded: "${aws_s3_bucket.assets.id}" },
+      ],
+    });
+    expect(g.edges).toEqual([]);
+  });
+
+  test("a cycle that also names a resource still yields the resource edge", () => {
+    const g = buildFixtureGraph({
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "app-assets" }] },
+        aws_lambda_function: { api: [{ environment: { variables: { B: "${local.x}" } } }] },
+      },
+      locals: [{ x: ["${local.y}", "${aws_s3_bucket.assets.arn}"], y: "${local.x}" }],
+    });
+    expect(inboundEdges(g, "aws_s3_bucket.assets")).toEqual([
+      { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn"], via: ["environment"] },
+    ]);
+  });
+
+  test("an output reading a local is still an output-tagged edge", () => {
+    const g = buildFixtureGraph({
+      resource: { aws_s3_bucket: { assets: [{ bucket: "app-assets" }] } },
+      locals: [{ assets_id: "${aws_s3_bucket.assets.id}" }],
+      output: { bucket_id: [{ value: "${local.assets_id}" }] },
+    });
+    expect(inboundEdges(g, "aws_s3_bucket.assets")).toEqual([
+      { from: "output.bucket_id", to: "aws_s3_bucket.assets", attrs: ["id"], via: ["value"], fromKind: "output" },
+    ]);
+  });
+
+  test("locals and data bodies reach the expression AST at all", () => {
+    expect(collectExpressions(threeRoutes)).toEqual([
+      "${aws_s3_bucket.assets.arn}",
+      "${aws_s3_bucket.assets.bucket}",
+      "${aws_s3_bucket.assets.id}",
+      "${data.aws_s3_bucket.lookup.arn}",
+      "${local.assets_id}",
+    ]);
+  });
+
+  test("a referrer is never an edge endpoint of its own", () => {
+    // The edge belongs to the surviving node, which is the thing a reader can
+    // carve or leave behind; the referrer is where the rewrite lands, not a
+    // participant. A local that names no resource contributes nothing at all.
+    const g = buildFixtureGraph(threeRoutes);
+    for (const referrer of ["local.assets_id", "data.aws_s3_bucket.lookup"]) {
+      expect([referrer, inboundEdges(g, referrer)]).toEqual([referrer, []]);
+      expect([referrer, outboundEdges(g, referrer)]).toEqual([referrer, []]);
+    }
+    expect(
+      buildFixtureGraph({
+        resource: { aws_lambda_function: { api: [{ environment: { variables: { B: "${local.env}" } } }] } },
+        locals: [{ env: "${var.stage}" }],
+      }).edges,
+    ).toEqual([]);
+  });
+});
+
 describe("refFromAccessor", () => {
   test("classifies resource, module, and data accessors", () => {
     expect(refFromAccessor("aws_s3_bucket.assets.bucket")).toEqual({

package/src/terraform/graph.ts

@@ -81,10 +81,32 @@ export function refFromAccessor(accessor: string): RawRef | null {
   return { address: `${parts[0]}.${parts[1]}`, attr: attrAfter(2) };
 }
 
+/**
+ * The referrer key a `local.<name>` accessor names, or null for anything else.
+ *
+ * `refFromAccessor` is right to refuse `local.*`: a local is a substitution,
+ * has no address in the plan graph, and nothing carves one. But the resource a
+ * local ultimately names is a dependency all the same, so the accessor is
+ * carried this far to be resolved through the locals table (#2324) rather than
+ * dropped at the resource-head guard.
+ */
+function localKeyFromAccessor(accessor: string): string | null {
+  const parts = accessorSegments(accessor);
+  const name = parts[1];
+  return parts[0] === "local" && name !== undefined && NAME.test(name) ? `local.${name}` : null;
+}
+
 /**
  * Every string value carrying an interpolation across the tree's resource,
- * module and output blocks — exactly the expressions `parse.ts` must resolve
- * through the AST before `buildGraph` can classify them.
+ * module, output, `locals` and `data` blocks — exactly the expressions
+ * `parse.ts` must resolve through the AST before `buildGraph` can classify
+ * them.
+ *
+ * `locals` and `data` are here because a reference can reach a resource
+ * through them (#2324): a survivor reading `local.assets_id`, or a `data`
+ * source keyed off the carved resource, is a dependency the plan breaks on
+ * just as hard as a direct one. Skipping their bodies meant the AST never saw
+ * those expressions at all.
  */
 export function collectExpressions(tree: Hcl2JsonTree): string[] {
   const exprs = new Set<string>();
@@ -100,6 +122,8 @@ export function collectExpressions(tree: Hcl2JsonTree): string[] {
   for (const named of Object.values(tree.resource ?? {})) for (const blocks of Object.values(named)) visit(blocks);
   for (const blocks of Object.values(tree.module ?? {})) visit(blocks);
   for (const blocks of Object.values(tree.output ?? {})) visit(blocks);
+  visit(tree.locals);
+  for (const named of Object.values(tree.data ?? {})) for (const blocks of Object.values(named)) visit(blocks);
   return [...exprs].sort();
 }
 
@@ -111,7 +135,12 @@ function refsInValue(value: unknown, exprRefs: ExpressionRefs): RawRef[] {
       if (!v.includes("${")) return;
       for (const accessor of exprRefs.get(v) ?? []) {
         const ref = refFromAccessor(accessor);
-        if (ref) refs.push(ref);
+        if (ref) {
+          refs.push(ref);
+          continue;
+        }
+        const localKey = localKeyFromAccessor(accessor);
+        if (localKey) refs.push({ address: localKey });
       }
     } else if (Array.isArray(v)) {
       v.forEach(visit);
@@ -137,6 +166,105 @@ function refsInBlock(block: unknown, exprRefs: ExpressionRefs): RawRef[] {
   return refs;
 }
 
+/**
+ * Non-node referrers: `local.<name>` and `data.<type>.<name>` → the references
+ * in the body each one stands for (#2324).
+ *
+ * Neither is a graph node — a local is a substitution, and a data source is
+ * not carvable infrastructure — but both sit on a path between a survivor and
+ * a resource, which is the shape an `output` block already has here. A
+ * `locals` block arrives from hcl2json as an array of its assignments, one
+ * element per `locals` block in the estate.
+ */
+function referrerTable(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): Map<string, RawRef[]> {
+  const table = new Map<string, RawRef[]>();
+  const add = (key: string, refs: RawRef[]): void => {
+    const existing = table.get(key);
+    if (existing) existing.push(...refs);
+    else table.set(key, refs);
+  };
+  const localsBlocks = Array.isArray(tree.locals) ? tree.locals : tree.locals ? [tree.locals] : [];
+  for (const block of localsBlocks) {
+    if (!block || typeof block !== "object") continue;
+    for (const [name, value] of Object.entries(block as Record<string, unknown>)) {
+      add(`local.${name}`, refsInValue(value, exprRefs));
+    }
+  }
+  for (const [type, named] of Object.entries(tree.data ?? {})) {
+    for (const [name, blocks] of Object.entries(named)) {
+      add(`data.${type}.${name}`, refsInBlock(Array.isArray(blocks) ? blocks[0] : blocks, exprRefs));
+    }
+  }
+  return table;
+}
+
+/** Identity of a reference for de-duplication: the address plus the attribute read off it. */
+function refKey(ref: RawRef): string {
+  return `${ref.address}\u0000${ref.attr ?? ""}`;
+}
+
+/**
+ * Resolve every referrer entry to the node references it ultimately names.
+ *
+ * One substitution pass is not enough: a local can read another local, and a
+ * `data` source can read a local that reads another data source. So this
+ * iterates to a fixpoint — each round replaces a referrer key appearing in an
+ * entry with that key's own resolved references, and the loop stops when a
+ * round adds nothing new.
+ *
+ * Growth is monotone and bounded by (referrers x distinct references), so a
+ * self-referential local (`a = local.a`, skipped outright) or a cycle
+ * (`a = local.b`, `b = local.a`) converges instead of recursing. Terraform
+ * rejects both, but the advisor only reads an estate and must not hang on one
+ * it disagrees with.
+ */
+function resolveReferrers(table: ReadonlyMap<string, RawRef[]>): Map<string, RawRef[]> {
+  // Seed each entry with the references that already name something outside
+  // the table; the loop then folds in what the referrer keys resolve to.
+  const resolved = new Map<string, Map<string, RawRef>>();
+  for (const [key, refs] of table) {
+    resolved.set(key, new Map(refs.filter((r) => !table.has(r.address)).map((r) => [refKey(r), r])));
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [key, refs] of table) {
+      const into = resolved.get(key)!;
+      for (const ref of refs) {
+        if (ref.address === key) continue; // `a = local.a` — nothing to fold in but itself
+        const from = resolved.get(ref.address);
+        if (!from) continue;
+        for (const [id, inner] of from) {
+          if (into.has(id)) continue;
+          into.set(id, inner);
+          changed = true;
+        }
+      }
+    }
+  }
+  return new Map([...resolved].map(([key, refs]) => [key, [...refs.values()]]));
+}
+
+/**
+ * A block's references as the graph should see them: one that reaches a
+ * `local` or `data` referrer additionally yields the node reference it
+ * resolves to.
+ *
+ * The original reference is kept — a `data.*` address is what marks the
+ * referring node dynamic, and an address that is not a node is dropped at edge
+ * time anyway. The resolved reference keeps the referring block's own `via`
+ * attribute, since that is what a deferred input is named after, and takes the
+ * carried resource attribute from the referrer's body.
+ */
+function throughReferrers(refs: readonly RawRef[], resolved: ReadonlyMap<string, RawRef[]>): RawRef[] {
+  const out: RawRef[] = [];
+  for (const ref of refs) {
+    out.push(ref);
+    for (const inner of resolved.get(ref.address) ?? []) out.push({ ...inner, via: ref.via });
+  }
+  return out;
+}
+
 /** A block carries `count`/`for_each` → dynamic, single instance until state resolves it. */
 function blockHasMeta(block: unknown, key: string): boolean {
   return !!block && typeof block === "object" && key in (block as Record<string, unknown>);
@@ -201,10 +329,20 @@ function dataSourceValues(block: unknown, type: string): Record<string, string>
  * exactly like a resource's does. So an output contributes an edge tagged
  * `fromKind: "output"` from the pseudo-address `output.<name>` (#1638),
  * which the scorer weights lower and `carve bridge` patches.
+ *
+ * `locals` and `data` blocks are non-node referrers of a third kind (#2324):
+ * they carry a reference between two nodes rather than terminating it. A
+ * survivor reading `local.assets_id`, or reading a `data` source keyed off the
+ * carved resource, depends on that resource, so the reference is resolved
+ * through the referrer to the resource it ultimately names and the edge is
+ * recorded against the surviving node — the thing a reader can actually carve
+ * or leave behind. The referrer's own body is where `carve bridge` then lands
+ * the rewrite.
  */
 export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGraph {
   const nodes: TfNode[] = [];
   const dataAddresses = new Set<string>();
+  const referrers = resolveReferrers(referrerTable(tree, exprRefs));
 
   // First pass: register data-source addresses so refs to them can be spotted.
   for (const [type, named] of Object.entries(tree.data ?? {})) {
@@ -218,7 +356,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
       const address = `${type}.${name}`;
       const block = Array.isArray(blocks) ? blocks[0] : blocks;
       const dynamic = blockHasMeta(block, "count") || blockHasMeta(block, "for_each");
-      const refs = refsInBlock(block, exprRefs);
+      const refs = throughReferrers(refsInBlock(block, exprRefs), referrers);
       const touchesData = refs.some((r) => dataAddresses.has(r.address));
       rawRefsByNode.set(address, refs);
       nodes.push({
@@ -239,7 +377,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
     const address = `module.${name}`;
     const block = Array.isArray(blocks) ? blocks[0] : blocks;
     const dynamic = blockHasMeta(block, "count") || blockHasMeta(block, "for_each");
-    const refs = refsInBlock(block, exprRefs);
+    const refs = throughReferrers(refsInBlock(block, exprRefs), referrers);
     const touchesData = refs.some((r) => dataAddresses.has(r.address));
     rawRefsByNode.set(address, refs);
     nodes.push({
@@ -256,7 +394,7 @@ export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGrap
   const outputRefs = new Map<string, RawRef[]>();
   for (const [name, blocks] of Object.entries(tree.output ?? {})) {
     const block = Array.isArray(blocks) ? blocks[0] : blocks;
-    outputRefs.set(`output.${name}`, refsInBlock(block, exprRefs));
+    outputRefs.set(`output.${name}`, throughReferrers(refsInBlock(block, exprRefs), referrers));
   }
 
   // Edges: keep only references that resolve to a known node.

package/src/terraform/parse.ts

@@ -68,7 +68,7 @@ async function resolveExpressionRefs(hcl2json: Hcl2Json, tree: Hcl2JsonTree): Pr
   return refs;
 }
 
-/** Deep-merge hcl2json trees across files (resource/module/data/output namespaces). */
+/** Deep-merge hcl2json trees across files (resource/module/data/output/locals namespaces). */
 function mergeTrees(into: Hcl2JsonTree, next: Hcl2JsonTree): void {
   for (const section of ["resource", "data"] as const) {
     const src = next[section];
@@ -82,6 +82,9 @@ function mergeTrees(into: Hcl2JsonTree, next: Hcl2JsonTree): void {
   // Outputs usually live in their own file (#1638) — merge them, or the graph
   // never sees the estate's outputs.tf at all.
   if (next.output) into.output = { ...(into.output ?? {}), ...next.output };
+  // `locals` is an array of blocks, not a keyed namespace, so files concatenate
+  // rather than overwrite — a `locals` block in every .tf is idiomatic (#2324).
+  if (next.locals) into.locals = [...(into.locals ?? []), ...next.locals];
 }
 
 /** List every `.tf` file directly under `dir` (non-recursive; matches Terraform's own module scoping). */

package/src/terraform/types.ts

@@ -97,5 +97,12 @@ export interface Hcl2JsonTree {
   data?: Record<string, Record<string, unknown[]>>;
   /** Root-module `output` blocks. Not nodes — they reference, they are not carvable (#1638). */
   output?: Record<string, unknown[]>;
+  /**
+   * Root-module `locals` blocks, as hcl2json renders them: one array element
+   * per `locals` block, each an object of its assignments. Not nodes either —
+   * a local is a substitution — but a reference can reach a resource through
+   * one, so the graph resolves `local.x` to what it names (#2324).
+   */
+  locals?: unknown[];
   [k: string]: unknown;
 }