@intentius/chant 0.41.20 → 0.42.1

package/src/terraform/graph.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
-import { buildGraph, inboundEdges, outboundEdges } from "./graph";
+import { inboundEdges, outboundEdges, refFromAccessor } from "./graph";
+import { buildFixtureGraph } from "./__fixtures__/build-graph";
 import type { Hcl2JsonTree } from "./types";
 
 /**
@@ -37,7 +38,7 @@ const workedExample: Hcl2JsonTree = {
 
 describe("buildGraph", () => {
   test("extracts resource nodes with addresses", () => {
-    const g = buildGraph(workedExample);
+    const g = buildFixtureGraph(workedExample);
     expect(g.nodes.map((n) => n.address)).toEqual([
       "aws_lambda_function.api",
       "aws_s3_bucket.assets",
@@ -47,16 +48,16 @@ describe("buildGraph", () => {
   });
 
   test("records directed edges with referenced attributes, deduped per target", () => {
-    const g = buildGraph(workedExample);
+    const g = buildFixtureGraph(workedExample);
     // versioning → bucket (.id), lambda → bucket (.bucket, .arn)
     expect(g.edges).toEqual([
-      { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"] },
-      { from: "aws_s3_bucket_versioning.assets", to: "aws_s3_bucket.assets", attrs: ["id"] },
+      { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"], via: ["environment"] },
+      { from: "aws_s3_bucket_versioning.assets", to: "aws_s3_bucket.assets", attrs: ["id"], via: ["bucket"] },
     ]);
   });
 
   test("inbound/outbound classification", () => {
-    const g = buildGraph(workedExample);
+    const g = buildFixtureGraph(workedExample);
     // Two survivors depend on the bucket; the bucket depends on nothing.
     expect(inboundEdges(g, "aws_s3_bucket.assets").map((e) => e.from)).toEqual([
       "aws_lambda_function.api",
@@ -78,7 +79,7 @@ describe("buildGraph", () => {
         aws_route53_record: { cdn: [{ name: "${module.cdn.domain}" }] },
       },
     };
-    const g = buildGraph(tree);
+    const g = buildFixtureGraph(tree);
     const cdn = g.nodes.find((n) => n.address === "module.cdn");
     expect(cdn).toMatchObject({ kind: "module", name: "cdn" });
     // module → bucket, and record → module
@@ -86,11 +87,13 @@ describe("buildGraph", () => {
       from: "module.cdn",
       to: "aws_s3_bucket.assets",
       attrs: ["arn"],
+      via: ["bucket_arn"],
     });
     expect(g.edges).toContainEqual({
       from: "aws_route53_record.cdn",
       to: "module.cdn",
       attrs: ["domain"],
+      via: ["name"],
     });
   });
 
@@ -104,7 +107,7 @@ describe("buildGraph", () => {
         },
       },
     };
-    const g = buildGraph(tree);
+    const g = buildFixtureGraph(tree);
     const byAddr = Object.fromEntries(g.nodes.map((n) => [n.address, n]));
     expect(byAddr["aws_instance.web"]).toMatchObject({ hasDynamic: true, instances: 1 });
     expect(byAddr["aws_instance.worker"]).toMatchObject({ hasDynamic: true, instances: 1 });
@@ -118,20 +121,63 @@ describe("buildGraph", () => {
         aws_instance: { web: [{ ami: "${data.aws_ami.ubuntu.id}" }] },
       },
     };
-    const g = buildGraph(tree);
+    const g = buildFixtureGraph(tree);
     expect(g.nodes.map((n) => n.address)).toEqual(["aws_instance.web"]); // data is not a node
     expect(g.edges).toEqual([]); // ref to data → no resource edge
     expect(g.nodes[0].hasDynamic).toBe(true);
   });
 
+  test("an expression whose AST found no references contributes no edge", () => {
+    // `${var.m["aws_s3_bucket.assets.arn"]}` — the AST reports only `var.m`;
+    // the quoted address inside the brackets is a map key, not a reference.
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "x" }] },
+        aws_lambda_function: { api: [{ handler: '${var.m["aws_s3_bucket.assets.arn"]}' }] },
+      },
+    };
+    const g = buildFixtureGraph(tree);
+    expect(g.edges).toEqual([]);
+  });
+
   test("var / local references are not edges", () => {
     const tree: Hcl2JsonTree = {
       resource: {
         aws_s3_bucket: { assets: [{ bucket: "${var.name}", tags: { env: "${local.env}" } }] },
       },
     };
-    const g = buildGraph(tree);
+    const g = buildFixtureGraph(tree);
     expect(g.edges).toEqual([]);
     expect(g.nodes[0].hasDynamic).toBe(false); // var/local alone are not the dynamic markers
   });
 });
+
+describe("refFromAccessor", () => {
+  test("classifies resource, module, and data accessors", () => {
+    expect(refFromAccessor("aws_s3_bucket.assets.bucket")).toEqual({
+      address: "aws_s3_bucket.assets",
+      attr: "bucket",
+    });
+    expect(refFromAccessor("aws_s3_bucket.assets")).toEqual({ address: "aws_s3_bucket.assets", attr: undefined });
+    expect(refFromAccessor("module.cdn.domain")).toEqual({ address: "module.cdn", attr: "domain" });
+    expect(refFromAccessor("data.aws_ami.ubuntu.id")).toEqual({ address: "data.aws_ami.ubuntu", attr: "id" });
+  });
+
+  test("non-resource heads are not references", () => {
+    for (const accessor of ["var.name", "local.env", "each.value", "count.index", "self.arn", "path.module", "terraform.workspace"]) {
+      expect(refFromAccessor(accessor)).toBeNull();
+    }
+  });
+
+  test("quoted map keys and numeric indexes never become the attribute", () => {
+    // `var.m["aws_s3_bucket.assets.arn"]` → the AST renders `var.m."aws_s3_bucket.assets.arn"`
+    expect(refFromAccessor('var.m."aws_s3_bucket.assets.arn"')).toBeNull();
+    // `aws_instance.web[0].id` → `aws_instance.web.0.id`
+    expect(refFromAccessor("aws_instance.web.0.id")).toEqual({ address: "aws_instance.web", attr: "id" });
+    // `aws_s3_bucket.assets.tags["a.b"]` → the key must not shadow the attr
+    expect(refFromAccessor('aws_s3_bucket.assets.tags."a.b"')).toEqual({
+      address: "aws_s3_bucket.assets",
+      attr: "tags",
+    });
+  });
+});

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) };
+}
+
+/**
+ * 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. */
-function refsInValue(value: unknown): RawRef[] {
+/** 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,6 +121,20 @@ 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>);
@@ -93,7 +158,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 +174,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 +194,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 +210,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 });