@intentius/chant 0.41.20 → 0.44.1

package/src/terraform/graph.ts

@@ -1,65 +1,116 @@
 /**
  * Pure Terraform dependency-graph builder for the carve-out advisor (#214 T1).
  *
- * Input is the JSON tree `@cdktf/hcl2json` produces (`Hcl2JsonTree`). No wasm,
- * no filesystem — so the graph and its edge classification are unit-testable
- * on hand-written fixtures. `parse.ts` is the thin glue that loads the wasm
- * parser and feeds this.
+ * Input is the JSON tree `@cdktf/hcl2json` produces (`Hcl2JsonTree`) plus the
+ * traversal accessors its expression AST found per interpolated string
+ * (`ExpressionRefs`, resolved in `parse.ts` — #998). Tokenizing `${...}`
+ * expression bodies is the AST's job — a quoted address inside an expression
+ * (`var.m["aws_s3_bucket.assets.arn"]`) or an escaped `$${...}` literal is not
+ * a reference, which the regex scan this replaced could not tell. This module
+ * only classifies the accessors the AST produced: no wasm, no filesystem, so
+ * graph building stays unit-testable on hand-written fixtures.
  */
 
 import { IDENTITY_ATTR } from "./tier-map";
 import type { Hcl2JsonTree, TfEdge, TfGraph, TfNode } from "./types";
 
 /**
- * hcl2json leaves interpolations as `${...}` strings. Match each expression
- * body; reference heads are extracted from it in `refsFromExpression`.
+ * Traversal accessors per interpolated string, as the hcl2json expression AST
+ * reports them (`getReferencesInExpression`): `"${aws_s3_bucket.assets.arn}"`
+ * maps to `["aws_s3_bucket.assets.arn"]`. Keys are the raw hcl2json string
+ * values; a missing key means the expression yielded no references.
  */
-const INTERPOLATION = /\$\{([^}]+)\}/g;
+export type ExpressionRefs = ReadonlyMap<string, readonly string[]>;
 
-/** `module.<name>` reference head. */
-const MODULE_REF = /\bmodule\.([A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_]+))?/g;
-
-/** `data.<type>.<name>` reference head. */
-const DATA_REF = /\bdata\.([a-z][a-z0-9_]*)\.([A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_]+))?/g;
-
-/**
- * `<type>.<name>` resource reference head. Deliberately broad — it also
- * matches `var.x`, `local.y`, `each.value`, function-ish tokens. Only heads
- * whose address is a known node survive into an edge (see `buildGraph`).
- */
-const RESOURCE_REF = /\b([a-z][a-z0-9_]*)\.([A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_]+))?/g;
-
-/** Non-resource reference prefixes that must never be read as a resource type. */
-const NON_RESOURCE_HEADS = new Set(["var", "local", "module", "data", "each", "count", "self", "path", "terraform"]);
+/** Non-resource reference heads that must never be read as a resource type. */
+const NON_RESOURCE_HEADS = new Set(["var", "local", "each", "count", "self", "path", "terraform"]);
 
 interface RawRef {
   address: string;
   attr?: string;
+  /** The referring block's top-level attribute the reference sits in (#998). */
+  via?: string;
 }
 
-/** Pull every resource/module/data reference out of one interpolation body. */
-function refsFromExpression(expr: string): RawRef[] {
-  const refs: RawRef[] = [];
-
-  for (const m of expr.matchAll(MODULE_REF)) {
-    refs.push({ address: `module.${m[1]}`, attr: m[2] });
+/**
+ * Split a traversal accessor into segments. Dots inside a quoted map key
+ * (`var.m."a.b"` — how the AST renders `var.m["a.b"]`) do not split.
+ */
+function accessorSegments(accessor: string): string[] {
+  const segments: string[] = [];
+  let i = 0;
+  while (i < accessor.length) {
+    if (accessor[i] === '"') {
+      const close = accessor.indexOf('"', i + 1);
+      const end = close === -1 ? accessor.length : close + 1;
+      segments.push(accessor.slice(i, end));
+      i = end;
+    } else {
+      let j = i;
+      while (j < accessor.length && accessor[j] !== ".") j++;
+      segments.push(accessor.slice(i, j));
+      i = j;
+    }
+    if (accessor[i] === ".") i++;
   }
-  for (const m of expr.matchAll(DATA_REF)) {
-    refs.push({ address: `data.${m[1]}.${m[2]}`, attr: m[3] });
+  return segments;
+}
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/**
+ * Classify one AST traversal accessor into a resource/module/data reference.
+ * `var.*`/`local.*`/`each.*`-headed accessors are not references; quoted map
+ * keys and numeric indexes never become the attribute.
+ */
+export function refFromAccessor(accessor: string): RawRef | null {
+  const parts = accessorSegments(accessor);
+  const isName = (s: string | undefined): s is string => s !== undefined && NAME.test(s);
+  const attrAfter = (idx: number): string | undefined => parts.slice(idx).find((p) => isName(p));
+
+  if (parts[0] === "module") {
+    return isName(parts[1]) ? { address: `module.${parts[1]}`, attr: attrAfter(2) } : null;
   }
-  for (const m of expr.matchAll(RESOURCE_REF)) {
-    if (NON_RESOURCE_HEADS.has(m[1])) continue;
-    refs.push({ address: `${m[1]}.${m[2]}`, attr: m[3] });
+  if (parts[0] === "data") {
+    return isName(parts[1]) && isName(parts[2])
+      ? { address: `data.${parts[1]}.${parts[2]}`, attr: attrAfter(3) }
+      : null;
   }
-  return refs;
+  if (NON_RESOURCE_HEADS.has(parts[0]) || !isName(parts[0]) || !isName(parts[1])) return null;
+  return { address: `${parts[0]}.${parts[1]}`, attr: attrAfter(2) };
 }
 
-/** Collect every `${...}` reference reachable in a block's value tree. */
-function refsInValue(value: unknown): RawRef[] {
+/**
+ * Every string value carrying an interpolation across the tree's resource and
+ * module blocks — exactly the expressions `parse.ts` must resolve through the
+ * AST before `buildGraph` can classify them.
+ */
+export function collectExpressions(tree: Hcl2JsonTree): string[] {
+  const exprs = new Set<string>();
+  const visit = (v: unknown): void => {
+    if (typeof v === "string") {
+      if (v.includes("${")) exprs.add(v);
+    } else if (Array.isArray(v)) {
+      v.forEach(visit);
+    } else if (v && typeof v === "object") {
+      for (const inner of Object.values(v as Record<string, unknown>)) visit(inner);
+    }
+  };
+  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);
+  return [...exprs].sort();
+}
+
+/** Collect every reference reachable in a block's value tree, via the AST-resolved accessors. */
+function refsInValue(value: unknown, exprRefs: ExpressionRefs): RawRef[] {
   const refs: RawRef[] = [];
   const visit = (v: unknown): void => {
     if (typeof v === "string") {
-      for (const m of v.matchAll(INTERPOLATION)) refs.push(...refsFromExpression(m[1]));
+      if (!v.includes("${")) return;
+      for (const accessor of exprRefs.get(v) ?? []) {
+        const ref = refFromAccessor(accessor);
+        if (ref) refs.push(ref);
+      }
     } else if (Array.isArray(v)) {
       v.forEach(visit);
     } else if (v && typeof v === "object") {
@@ -70,16 +121,40 @@ function refsInValue(value: unknown): RawRef[] {
   return refs;
 }
 
+/**
+ * References in a whole block, each tagged with the top-level attribute it
+ * came in through — `via` is what a deferred outbound input gets named after
+ * when emit turns it into a build parameter (#998).
+ */
+function refsInBlock(block: unknown, exprRefs: ExpressionRefs): RawRef[] {
+  if (!block || typeof block !== "object" || Array.isArray(block)) return refsInValue(block, exprRefs);
+  const refs: RawRef[] = [];
+  for (const [key, value] of Object.entries(block as Record<string, unknown>)) {
+    for (const ref of refsInValue(value, exprRefs)) refs.push({ ...ref, via: key });
+  }
+  return refs;
+}
+
 /** 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>);
 }
 
-/** The resource's physical name, if its identity attribute is a plain literal (not interpolated). */
+/**
+ * The resource's physical name, if its identity attribute is a plain literal
+ * (not interpolated). A dotted `IDENTITY_ATTR` entry walks nested blocks —
+ * hcl2json renders a nested block as a one-element array, so arrays step
+ * through their first element (`manifest.metadata.name`).
+ */
 function literalIdentity(block: unknown, type: string): string | undefined {
   const attr = IDENTITY_ATTR[type];
   if (!attr || !block || typeof block !== "object") return undefined;
-  const value = (block as Record<string, unknown>)[attr];
+  let value: unknown = block;
+  for (const segment of attr.split(".")) {
+    if (Array.isArray(value)) value = value[0];
+    if (!value || typeof value !== "object") return undefined;
+    value = (value as Record<string, unknown>)[segment];
+  }
   if (typeof value !== "string" || value.includes("${")) return undefined;
   return value;
 }
@@ -93,7 +168,7 @@ function literalIdentity(block: unknown, type: string): string | undefined {
  * resolves to a known resource/module node — references to `var`/`local`/data
  * are dropped.
  */
-export function buildGraph(tree: Hcl2JsonTree): TfGraph {
+export function buildGraph(tree: Hcl2JsonTree, exprRefs: ExpressionRefs): TfGraph {
   const nodes: TfNode[] = [];
   const dataAddresses = new Set<string>();
 
@@ -109,7 +184,7 @@ export function buildGraph(tree: Hcl2JsonTree): TfGraph {
       const address = `${type}.${name}`;
       const block = Array.isArray(blocks) ? blocks[0] : blocks;
       const dynamic = blockHasMeta(block, "count") || blockHasMeta(block, "for_each");
-      const refs = refsInValue(block);
+      const refs = refsInBlock(block, exprRefs);
       const touchesData = refs.some((r) => dataAddresses.has(r.address));
       rawRefsByNode.set(address, refs);
       nodes.push({
@@ -129,7 +204,7 @@ export function buildGraph(tree: Hcl2JsonTree): TfGraph {
     const address = `module.${name}`;
     const block = Array.isArray(blocks) ? blocks[0] : blocks;
     const dynamic = blockHasMeta(block, "count") || blockHasMeta(block, "for_each");
-    const refs = refsInValue(block);
+    const refs = refsInBlock(block, exprRefs);
     const touchesData = refs.some((r) => dataAddresses.has(r.address));
     rawRefsByNode.set(address, refs);
     nodes.push({
@@ -145,14 +220,16 @@ export function buildGraph(tree: Hcl2JsonTree): TfGraph {
   const known = new Set(nodes.map((n) => n.address));
   const edges: TfEdge[] = [];
   for (const [from, refs] of rawRefsByNode) {
-    const byTarget = new Map<string, Set<string>>();
+    const byTarget = new Map<string, { attrs: Set<string>; via: Set<string> }>();
     for (const ref of refs) {
       if (ref.address === from || !known.has(ref.address)) continue;
-      if (!byTarget.has(ref.address)) byTarget.set(ref.address, new Set());
-      if (ref.attr) byTarget.get(ref.address)!.add(ref.attr);
+      if (!byTarget.has(ref.address)) byTarget.set(ref.address, { attrs: new Set(), via: new Set() });
+      const target = byTarget.get(ref.address)!;
+      if (ref.attr) target.attrs.add(ref.attr);
+      if (ref.via) target.via.add(ref.via);
     }
-    for (const [to, attrs] of byTarget) {
-      edges.push({ from, to, attrs: [...attrs].sort() });
+    for (const [to, { attrs, via }] of byTarget) {
+      edges.push({ from, to, attrs: [...attrs].sort(), via: [...via].sort() });
     }
   }
 

package/src/terraform/manifest.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  carveManifestPath,
+  listCarveManifests,
+  readCarveManifest,
+  resolveCarveManifest,
+  updateCarveManifest,
+  writeCarveManifest,
+  type CarveManifest,
+} from "./manifest";
+import type { CarveReport } from "./carve";
+
+function report(target: string): CarveReport {
+  return {
+    target,
+    carveSet: [{ address: target, type: target.split(".")[0] }],
+    peelability: 90,
+    inbound: [],
+    outbound: [],
+    reversible: true,
+    diagnostics: [],
+  };
+}
+
+function manifest(target: string): CarveManifest {
+  return { version: 1, target, from: "/estate", boundary: report(target) };
+}
+
+function withDir<T>(fn: (dir: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), "chant-manifest-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carve manifest", () => {
+  test("round-trips through the output dir, named by target slug", () => {
+    withDir((dir) => {
+      const path = writeCarveManifest(dir, manifest("aws_s3_bucket.assets"));
+      expect(path).toBe(join(dir, "aws_s3_bucket-assets.carve.json"));
+      expect(path).toBe(carveManifestPath(dir, "aws_s3_bucket.assets"));
+      const read = readCarveManifest(path)!;
+      expect(read.target).toBe("aws_s3_bucket.assets");
+      expect(read.boundary.peelability).toBe(90);
+    });
+  });
+
+  test("rejects missing, malformed, and wrong-version files", () => {
+    withDir((dir) => {
+      expect(readCarveManifest(join(dir, "nope.carve.json"))).toBeNull();
+      writeFileSync(join(dir, "bad.carve.json"), "not json");
+      expect(readCarveManifest(join(dir, "bad.carve.json"))).toBeNull();
+      writeFileSync(join(dir, "v9.carve.json"), JSON.stringify({ version: 9, target: "x" }));
+      expect(readCarveManifest(join(dir, "v9.carve.json"))).toBeNull();
+    });
+  });
+
+  test("resolve: no select + exactly one manifest composes; none or several is a clear error", () => {
+    withDir((dir) => {
+      expect(resolveCarveManifest(dir).error).toContain("--select");
+
+      writeCarveManifest(dir, manifest("aws_s3_bucket.assets"));
+      const one = resolveCarveManifest(dir);
+      expect(one.manifest!.target).toBe("aws_s3_bucket.assets");
+      expect(one.error).toBeUndefined();
+
+      writeCarveManifest(dir, manifest("aws_sqs_queue.jobs"));
+      const many = resolveCarveManifest(dir);
+      expect(many.error).toContain("aws_s3_bucket.assets");
+      expect(many.error).toContain("aws_sqs_queue.jobs");
+      expect(listCarveManifests(dir)).toHaveLength(2);
+
+      // An explicit select still resolves its own manifest among several.
+      const picked = resolveCarveManifest(dir, "aws_sqs_queue.jobs");
+      expect(picked.manifest!.target).toBe("aws_sqs_queue.jobs");
+    });
+  });
+
+  test("resolve with a select whose manifest is absent runs standalone (no error)", () => {
+    withDir((dir) => {
+      const res = resolveCarveManifest(dir, "aws_s3_bucket.assets");
+      expect(res.manifest).toBeUndefined();
+      expect(res.error).toBeUndefined();
+    });
+  });
+
+  test("update patches an existing manifest and no-ops on a missing one", () => {
+    withDir((dir) => {
+      expect(updateCarveManifest(dir, "aws_s3_bucket.assets", { bridge: { written: [], appliedInPlace: false, at: "t" } })).toBeUndefined();
+
+      writeCarveManifest(dir, manifest("aws_s3_bucket.assets"));
+      const path = updateCarveManifest(dir, "aws_s3_bucket.assets", {
+        apply: { marker: { stack: "assets", env: "prod" }, ownershipTags: { "chant:managed-by": "chant" }, at: "t" },
+      })!;
+      const read = readCarveManifest(path)!;
+      expect(read.apply!.marker).toEqual({ stack: "assets", env: "prod" });
+      expect(read.boundary.target).toBe("aws_s3_bucket.assets"); // untouched sections survive
+    });
+  });
+});

package/src/terraform/manifest.ts

@@ -0,0 +1,162 @@
+/**
+ * The carve state manifest (#998) — what makes emit → bridge → apply compose.
+ *
+ * `carve emit` persists the boundary report and adoption selector next to the
+ * emitted source as `<target>.carve.json`. The later steps read it back from
+ * their output dir, so `carve bridge` and `carve apply` no longer need the
+ * target re-specified by hand, and each step records what it did for the next.
+ * Plain JSON on disk — reviewable, diffable, nothing proprietary.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { CarveReport } from "./carve";
+import type { OwnershipMarker } from "../ownership";
+
+export const CARVE_MANIFEST_SUFFIX = ".carve.json";
+
+export interface CarveManifest {
+  version: 1;
+  /** Terraform address of the carved resource, e.g. `aws_s3_bucket.assets`. */
+  target: string;
+  /** Terraform resource type, when known. */
+  tfType?: string;
+  /** Absolute path of the Terraform estate the carve came from. */
+  from: string;
+  /** Absolute path of the tfstate used for adoption (offline path). */
+  statePath?: string;
+  /** Boundary classification persisted when the manifest was written. */
+  boundary: CarveReport;
+  /** Recorded by `carve emit`. */
+  emit?: {
+    source: "tfstate" | "live";
+    /** Emitted chant source file path(s). */
+    files: string[];
+    /**
+     * Deferred outbound inputs declared as build parameters in the emitted
+     * project (#998), keyed by parameter name.
+     */
+    params?: Record<
+      string,
+      {
+        /** The carved resource's own Terraform attribute the value enters through. */
+        tfAttr: string;
+        /** The survivor the Terraform source read, e.g. `aws_vpc.main`. */
+        survivor: string;
+        /** Survivor attribute(s) read. */
+        attrs: string[];
+        /** State-resolved default, when scalar. */
+        default?: string | number | boolean;
+      }
+    >;
+    at: string;
+  };
+  /** Recorded by `carve bridge`. */
+  bridge?: {
+    written: string[];
+    appliedInPlace: boolean;
+    /** The git-applyable `.patch` carrying the whole survivor edit. */
+    patch?: string;
+    /** Carved addresses whose own `.tf` block the rewrites remove (#998). */
+    excised?: string[];
+    at: string;
+  };
+  /** Recorded by `carve apply`. */
+  apply?: {
+    marker: OwnershipMarker;
+    ownershipTags: Record<string, string>;
+    /** Emitted files the marker was stamped into (`--write-source`). */
+    stampedFiles?: string[];
+    at: string;
+  };
+}
+
+/** Filesystem-safe slug for a Terraform address (shared file-naming convention). */
+export function carveSlug(target: string): string {
+  return target.replace(/[^A-Za-z0-9_]+/g, "-");
+}
+
+/** Where the manifest for `target` lives inside an output dir. */
+export function carveManifestPath(outDir: string, target: string): string {
+  return join(outDir, `${carveSlug(target)}${CARVE_MANIFEST_SUFFIX}`);
+}
+
+/** Write (or overwrite) a manifest into the output dir. Returns the path. */
+export function writeCarveManifest(outDir: string, manifest: CarveManifest): string {
+  mkdirSync(outDir, { recursive: true });
+  const path = carveManifestPath(outDir, manifest.target);
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+  return path;
+}
+
+/** Read a manifest, or null when absent/unreadable/not a v1 manifest. */
+export function readCarveManifest(path: string): CarveManifest | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as CarveManifest;
+    if (parsed?.version !== 1) return null;
+    if (typeof parsed.target !== "string" || typeof parsed.boundary !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** All carve manifest paths in an output dir. */
+export function listCarveManifests(outDir: string): string[] {
+  if (!existsSync(outDir)) return [];
+  return readdirSync(outDir)
+    .filter((f) => f.endsWith(CARVE_MANIFEST_SUFFIX))
+    .map((f) => join(outDir, f))
+    .sort();
+}
+
+export interface ResolvedManifest {
+  manifest?: CarveManifest;
+  path?: string;
+  error?: string;
+}
+
+/**
+ * Resolve the manifest a later carve step composes with. With a selected
+ * target, that target's manifest (absent is fine — the step just runs
+ * standalone). Without one, the single manifest in the output dir; none or
+ * several is an error naming what is (or is not) there.
+ */
+export function resolveCarveManifest(outDir: string, select?: string): ResolvedManifest {
+  if (select) {
+    const path = carveManifestPath(outDir, select);
+    const manifest = readCarveManifest(path);
+    return manifest ? { manifest, path } : {};
+  }
+
+  const paths = listCarveManifests(outDir);
+  if (paths.length === 0) {
+    return { error: `No carve manifest in ${outDir} — run \`chant carve emit\` first, or pass --select <tf-address>.` };
+  }
+  const manifests = paths
+    .map((path) => ({ path, manifest: readCarveManifest(path) }))
+    .filter((m): m is { path: string; manifest: CarveManifest } => m.manifest !== null);
+  if (manifests.length === 0) {
+    return { error: `No readable carve manifest in ${outDir} — pass --select <tf-address>.` };
+  }
+  if (manifests.length > 1) {
+    const targets = manifests.map((m) => m.manifest.target).join(", ");
+    return { error: `Several carves in ${outDir} (${targets}) — pass --select <tf-address> to pick one.` };
+  }
+  return { manifest: manifests[0].manifest, path: manifests[0].path };
+}
+
+/** Read-modify-write a section of an existing manifest. No-op when absent. */
+export function updateCarveManifest(
+  outDir: string,
+  target: string,
+  patch: Partial<Pick<CarveManifest, "boundary" | "emit" | "bridge" | "apply">>,
+): string | undefined {
+  const path = carveManifestPath(outDir, target);
+  const manifest = readCarveManifest(path);
+  if (!manifest) return undefined;
+  Object.assign(manifest, patch);
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+  return path;
+}

package/src/terraform/parse.test.ts

@@ -47,7 +47,45 @@ describe.runIf(true)("parseTerraformDir (real wasm)", () => {
         "aws_s3_bucket.assets",
       ]);
       expect(g.edges).toEqual([
-        { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"] },
+        { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"], via: ["environment"] },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("edge detection is AST-driven: string literals and escapes are not references", async () => {
+    if (!parserAvailable) return; // optional dep absent — skip
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf-ast-"));
+    try {
+      writeFileSync(
+        join(dir, "main.tf"),
+        [
+          `resource "aws_s3_bucket" "assets" {`,
+          `  bucket = "myapp-assets-prod"`,
+          `}`,
+          `resource "aws_cloudwatch_log_group" "api" {`,
+          `  name = "/myapp/api"`,
+          `}`,
+          `resource "aws_lambda_function" "api" {`,
+          `  environment {`,
+          `    variables = {`,
+          `      # a quoted address is a map key, not a reference`,
+          `      LOG_GROUP = var.settings["aws_cloudwatch_log_group.api.name"]`,
+          `      # an escaped interpolation is a literal, not a reference`,
+          `      ESCAPED = "$\${aws_s3_bucket.assets.id}"`,
+          `      # references survive function calls and conditionals`,
+          `      URL = format("s3://%s", aws_s3_bucket.assets.bucket)`,
+          `      ARN = var.on ? aws_s3_bucket.assets.arn : ""`,
+          `    }`,
+          `  }`,
+          `}`,
+        ].join("\n") + "\n",
+      );
+      const g = await parseTerraformDir(dir);
+      // No phantom edge to the log group; real refs found through format()/?: .
+      expect(g.edges).toEqual([
+        { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"], via: ["environment"] },
       ]);
     } finally {
       rmSync(dir, { recursive: true, force: true });

package/src/terraform/parse.ts

@@ -10,12 +10,16 @@
 
 import { readdirSync, readFileSync } from "fs";
 import { join } from "path";
-import { buildGraph } from "./graph";
+import { buildGraph, collectExpressions, type ExpressionRefs } from "./graph";
 import { readStateInstanceCounts, applyStateCounts } from "./state";
 import type { Hcl2JsonTree, TfGraph } from "./types";
 
-/** Minimal shape of the parser export we depend on. */
-type Hcl2JsonParse = (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
+/** Minimal shape of the parser exports we depend on. */
+export interface Hcl2Json {
+  parse: (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
+  /** Expression-AST reference extraction (#998) — one traversal accessor per reference. */
+  getReferencesInExpression: (filename: string, expression: string) => Promise<Array<{ value: string }>>;
+}
 
 export class Hcl2JsonNotInstalled extends Error {
   constructor(cause: unknown) {
@@ -32,15 +36,38 @@ export class Hcl2JsonNotInstalled extends Error {
  * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
  * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
  */
-export async function loadHcl2json(): Promise<Hcl2JsonParse> {
+export async function loadHcl2json(): Promise<Hcl2Json> {
   try {
-    const mod = (await import("@cdktf/hcl2json")) as { parse: Hcl2JsonParse };
-    return mod.parse;
+    return (await import("@cdktf/hcl2json")) as Hcl2Json;
   } catch (err) {
     throw new Hcl2JsonNotInstalled(err);
   }
 }
 
+/**
+ * Resolve every interpolated string in the merged tree through the parser's
+ * expression AST (`getReferencesInExpression`), producing the accessor map
+ * `buildGraph` classifies. The AST — not a regex over the expression body —
+ * decides what is a reference, so a quoted address used as a map key or an
+ * escaped `$${...}` literal yields none. An expression the AST cannot parse in
+ * isolation resolves to no references (fewer edges, never a phantom one).
+ */
+async function resolveExpressionRefs(hcl2json: Hcl2Json, tree: Hcl2JsonTree): Promise<ExpressionRefs> {
+  const refs = new Map<string, string[]>();
+  for (const expr of collectExpressions(tree)) {
+    try {
+      const found = await hcl2json.getReferencesInExpression("expression.tf", expr);
+      refs.set(
+        expr,
+        found.map((r) => r.value),
+      );
+    } catch {
+      refs.set(expr, []);
+    }
+  }
+  return refs;
+}
+
 /** Deep-merge hcl2json trees across files (resource/module/data namespaces). */
 function mergeTrees(into: Hcl2JsonTree, next: Hcl2JsonTree): void {
   for (const section of ["resource", "data"] as const) {
@@ -74,14 +101,14 @@ export interface ParseTerraformOptions {
  * instance counts become accurate (see `state.ts`).
  */
 export async function parseTerraformDir(dir: string, opts: ParseTerraformOptions = {}): Promise<TfGraph> {
-  const parse = await loadHcl2json();
+  const hcl2json = await loadHcl2json();
   const files = listTfFiles(dir);
   const merged: Hcl2JsonTree = {};
   for (const file of files) {
-    const tree = await parse(file, readFileSync(file, "utf-8"));
+    const tree = await hcl2json.parse(file, readFileSync(file, "utf-8"));
     mergeTrees(merged, tree);
   }
-  const graph = buildGraph(merged);
+  const graph = buildGraph(merged, await resolveExpressionRefs(hcl2json, merged));
   if (opts.statePath) applyStateCounts(graph, readStateInstanceCounts(opts.statePath));
   return graph;
 }