@intentius/chant 0.18.37 → 0.19.1

package/src/terraform/carve.test.ts

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { resolveCarveSet, boundaryReport } from "./carve";
+import type { Hcl2JsonTree } from "./types";
+
+// #197 worked example: a bucket a Lambda reads, with a versioning sub-resource.
+const workedExample: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_s3_bucket_versioning: {
+      assets: [{ bucket: "${aws_s3_bucket.assets.id}", versioning_configuration: { status: "Enabled" } }],
+    },
+    aws_lambda_function: {
+      api: [
+        {
+          environment: {
+            variables: {
+              ASSETS_BUCKET: "${aws_s3_bucket.assets.bucket}",
+              ASSETS_ARN: "${aws_s3_bucket.assets.arn}",
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+describe("resolveCarveSet", () => {
+  test("selected node plus its folded sub-resources", () => {
+    const set = resolveCarveSet(buildGraph(workedExample), "aws_s3_bucket.assets");
+    expect(set.map((m) => m.address).sort()).toEqual([
+      "aws_s3_bucket.assets",
+      "aws_s3_bucket_versioning.assets",
+    ]);
+    const folded = set.find((m) => m.address === "aws_s3_bucket_versioning.assets");
+    expect(folded?.foldedInto).toBe("aws_s3_bucket.assets");
+  });
+
+  test("empty for an unknown address", () => {
+    expect(resolveCarveSet(buildGraph(workedExample), "aws_s3_bucket.nope")).toEqual([]);
+  });
+});
+
+describe("boundaryReport", () => {
+  test("classifies the Lambda inbound edge; folds the versioning internal edge away", () => {
+    const report = boundaryReport(buildGraph(workedExample), "aws_s3_bucket.assets")!;
+    expect(report.target).toBe("aws_s3_bucket.assets");
+    expect(report.peelability).toBe(88);
+    expect(report.reversible).toBe(true);
+
+    // The only boundary edge is the Lambda → bucket inbound; the versioning →
+    // bucket edge is internal to the carve set and dropped.
+    expect(report.inbound).toEqual([
+      {
+        direction: "inbound",
+        survivor: "aws_lambda_function.api",
+        carved: "aws_s3_bucket.assets",
+        attrs: ["arn", "bucket"],
+        bridge: "tf-data-source",
+        required: "immediately",
+      },
+    ]);
+    expect(report.outbound).toEqual([]);
+  });
+
+  test("outbound edges become deferred inputs", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sns_topic: { alerts: [{ name: "a" }] },
+        aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
+      },
+    };
+    // Carve the queue: it depends on the topic (a survivor) → outbound/deferred.
+    const report = boundaryReport(buildGraph(tree), "aws_sqs_queue.dlq")!;
+    expect(report.inbound).toEqual([]);
+    expect(report.outbound).toEqual([
+      {
+        direction: "outbound",
+        survivor: "aws_sns_topic.alerts",
+        carved: "aws_sqs_queue.dlq",
+        attrs: ["arn"],
+        bridge: "deferred-input",
+        required: "at-apply",
+      },
+    ]);
+  });
+
+  test("unsupported type is flagged in diagnostics", () => {
+    const tree: Hcl2JsonTree = { resource: { random_pet: { n: [{ length: 2 }] } } };
+    const report = boundaryReport(buildGraph(tree), "random_pet.n")!;
+    expect(report.diagnostics.join(" ")).toMatch(/no known native mapping/i);
+  });
+
+  test("null for an unknown target", () => {
+    expect(boundaryReport(buildGraph(workedExample), "aws_s3_bucket.nope")).toBeNull();
+  });
+});

package/src/terraform/graduate.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { boundaryReport } from "./carve";
+import { graduationPlan, DEFAULT_TAG_OWNERSHIP_KEYS } from "./graduate";
+import type { Hcl2JsonTree } from "./types";
+
+const bucketTree: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: { assets: [{ bucket: "myapp-assets-prod" }] },
+    aws_lambda_function: { api: [{ x: "${aws_s3_bucket.assets.arn}" }] },
+  },
+};
+
+describe("graduationPlan", () => {
+  test("resolves the ownership marker + tags (chant-owned)", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report, { stack: "assets", env: "prod" });
+
+    expect(plan.marker).toEqual({ stack: "assets", env: "prod" });
+    expect(plan.ownershipTags).toEqual({
+      [DEFAULT_TAG_OWNERSHIP_KEYS.managedBy]: "chant",
+      [DEFAULT_TAG_OWNERSHIP_KEYS.stack]: "assets",
+      [DEFAULT_TAG_OWNERSHIP_KEYS.env]: "prod",
+    });
+  });
+
+  test("stack defaults to the resource's local name", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report);
+    expect(plan.marker.stack).toBe("assets");
+    expect(plan.ownershipTags).not.toHaveProperty(DEFAULT_TAG_OWNERSHIP_KEYS.env); // no env → omitted
+  });
+
+  test("runbook is reversible and BYOL (import rollback, no chant-runs-apply)", () => {
+    const report = boundaryReport(buildGraph(bucketTree), "aws_s3_bucket.assets")!;
+    const plan = graduationPlan(report, { env: "prod" });
+    const runbook = plan.steps.join("\n");
+    expect(runbook).toMatch(/terraform import aws_s3_bucket\.assets/);
+    expect(runbook).toMatch(/cloudformation deploy|ApplyOp/);
+    expect(runbook).toMatch(/lifecycle diff --live/);
+  });
+
+  test("warns when outbound edges leave deferred inputs to wire", () => {
+    // Carve the Lambda: it depends on the bucket (survivor) → outbound/deferred.
+    const report = boundaryReport(buildGraph(bucketTree), "aws_lambda_function.api")!;
+    const plan = graduationPlan(report, { env: "prod" });
+    expect(plan.warnings.join(" ")).toMatch(/deferred deploy-time input/i);
+  });
+});

package/src/terraform/graduate.ts

@@ -0,0 +1,78 @@
+/**
+ * Apply graduation for the strangler-fig carve (#197) — the last step.
+ *
+ * After a resource is emitted (`carve emit`) and the survivors are bridged
+ * (`carve bridge`), it sits at the observe position: chant has the source, but
+ * the live resource is an orphan carrying no chant ownership. Graduation is the
+ * dial-turn to apply: mark the resource chant-owned so `chant carve` / status
+ * recognize it, and finalize the ordered apply runbook.
+ *
+ * This is BYOL-honest: it does NOT call the cloud. It resolves the ownership
+ * marker (reusing core's `ownershipEntries`) and produces the graduation
+ * artifacts + runbook. The apply itself is whatever lifecycle you brought —
+ * the native CLI, a CI pipeline, an ApplyOp — and it stamps the marker the
+ * emitted source now carries.
+ */
+
+import { ownershipEntries, type ChannelKeys, type OwnershipMarker } from "../ownership";
+import type { CarveReport } from "./carve";
+
+/**
+ * Default tag channel, mirroring the AWS lexicon's `AWS_TAG_OWNERSHIP_KEYS`
+ * (`lexicons/aws/src/ownership.ts`). Core cannot import a lexicon, so the
+ * convention is duplicated here; the values match so the graduation plan shows
+ * the tags the AWS apply path will actually stamp.
+ */
+export const DEFAULT_TAG_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "chant:managed-by",
+  stack: "chant:stack",
+  env: "chant:env",
+};
+
+export interface GraduationPlan {
+  target: string;
+  marker: OwnershipMarker;
+  /** The ownership tags the emitted resource must carry to be chant-owned. */
+  ownershipTags: Record<string, string>;
+  /** The finalized, ordered apply runbook. */
+  steps: string[];
+  warnings: string[];
+}
+
+export interface GraduationOptions {
+  /** Chant stack name for the ownership marker (defaults to the resource name). */
+  stack?: string;
+  /** Environment identity for the marker. */
+  env?: string;
+  /** Override the tag channel (e.g. for a non-AWS lexicon). */
+  channel?: ChannelKeys;
+}
+
+export function graduationPlan(report: CarveReport, opts: GraduationOptions = {}): GraduationPlan {
+  const stack = opts.stack ?? (report.target.split(".").slice(1).join(".") || report.target);
+  const marker: OwnershipMarker = { stack, env: opts.env };
+  const ownershipTags = ownershipEntries(opts.channel ?? DEFAULT_TAG_OWNERSHIP_KEYS, marker);
+
+  const warnings: string[] = [];
+  if (report.outbound.length) {
+    warnings.push(
+      `${report.outbound.length} deferred deploy-time input(s) must be wired before apply (see the boundary report).`,
+    );
+  }
+
+  const tagList = Object.entries(ownershipTags)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(", ");
+
+  const steps = [
+    `1. Confirm the emitted source builds spec-true:  chant build <emitted-src> -o ${report.target}.template.json`,
+    `2. Add the ownership marker so chant owns the resource — tags: ${tagList}`,
+    `3. Apply with your lifecycle (BYOL), e.g.:`,
+    `     aws cloudformation deploy --template-file ${report.target}.template.json --stack-name ${stack} ...`,
+    `   or graduate to an ApplyOp for a durable, gated apply.`,
+    `4. Verify chant now owns it:  chant lifecycle diff --live <env>   (expect: unchanged, owned)`,
+    `Rollback before this point:  terraform import ${report.target} <physical-id>`,
+  ];
+
+  return { target: report.target, marker, ownershipTags, steps, warnings };
+}

package/src/terraform/graph.test.ts

@@ -0,0 +1,137 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph, inboundEdges, outboundEdges } from "./graph";
+import type { Hcl2JsonTree } from "./types";
+
+/**
+ * The #197 worked example, in the JSON shape `@cdktf/hcl2json` emits: a bucket,
+ * its versioning sub-resource, and a Lambda that reads the bucket's name + arn.
+ */
+const workedExample: Hcl2JsonTree = {
+  resource: {
+    aws_s3_bucket: {
+      assets: [{ bucket: "myapp-assets-prod", tags: { Team: "web", Env: "prod" } }],
+    },
+    aws_s3_bucket_versioning: {
+      assets: [
+        {
+          bucket: "${aws_s3_bucket.assets.id}",
+          versioning_configuration: { status: "Enabled" },
+        },
+      ],
+    },
+    aws_lambda_function: {
+      api: [
+        {
+          function_name: "myapp-api",
+          environment: {
+            variables: {
+              ASSETS_BUCKET: "${aws_s3_bucket.assets.bucket}",
+              ASSETS_ARN: "${aws_s3_bucket.assets.arn}",
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+describe("buildGraph", () => {
+  test("extracts resource nodes with addresses", () => {
+    const g = buildGraph(workedExample);
+    expect(g.nodes.map((n) => n.address)).toEqual([
+      "aws_lambda_function.api",
+      "aws_s3_bucket.assets",
+      "aws_s3_bucket_versioning.assets",
+    ]);
+    expect(g.nodes.every((n) => n.kind === "resource")).toBe(true);
+  });
+
+  test("records directed edges with referenced attributes, deduped per target", () => {
+    const g = buildGraph(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"] },
+    ]);
+  });
+
+  test("inbound/outbound classification", () => {
+    const g = buildGraph(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",
+      "aws_s3_bucket_versioning.assets",
+    ]);
+    expect(outboundEdges(g, "aws_s3_bucket.assets")).toEqual([]);
+    // The Lambda depends on the bucket (outbound) and nothing depends on it.
+    expect(outboundEdges(g, "aws_lambda_function.api").map((e) => e.to)).toEqual([
+      "aws_s3_bucket.assets",
+    ]);
+    expect(inboundEdges(g, "aws_lambda_function.api")).toEqual([]);
+  });
+
+  test("module blocks become nodes and are referenceable", () => {
+    const tree: Hcl2JsonTree = {
+      module: { cdn: [{ source: "./cdn", bucket_arn: "${aws_s3_bucket.assets.arn}" }] },
+      resource: {
+        aws_s3_bucket: { assets: [{ bucket: "x" }] },
+        aws_route53_record: { cdn: [{ name: "${module.cdn.domain}" }] },
+      },
+    };
+    const g = buildGraph(tree);
+    const cdn = g.nodes.find((n) => n.address === "module.cdn");
+    expect(cdn).toMatchObject({ kind: "module", name: "cdn" });
+    // module → bucket, and record → module
+    expect(g.edges).toContainEqual({
+      from: "module.cdn",
+      to: "aws_s3_bucket.assets",
+      attrs: ["arn"],
+    });
+    expect(g.edges).toContainEqual({
+      from: "aws_route53_record.cdn",
+      to: "module.cdn",
+      attrs: ["domain"],
+    });
+  });
+
+  test("count / for_each mark a node dynamic (single instance until state resolves)", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_instance: {
+          web: [{ count: 3, ami: "ami-123" }],
+          worker: [{ for_each: "${var.workers}", ami: "ami-456" }],
+          bastion: [{ ami: "ami-789" }],
+        },
+      },
+    };
+    const g = buildGraph(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 });
+    expect(byAddr["aws_instance.bastion"]).toMatchObject({ hasDynamic: false, instances: 1 });
+  });
+
+  test("a reference to a data source marks the referrer dynamic but is not an edge", () => {
+    const tree: Hcl2JsonTree = {
+      data: { aws_ami: { ubuntu: [{ owners: ["099720109477"] }] } },
+      resource: {
+        aws_instance: { web: [{ ami: "${data.aws_ami.ubuntu.id}" }] },
+      },
+    };
+    const g = buildGraph(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("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);
+    expect(g.edges).toEqual([]);
+    expect(g.nodes[0].hasDynamic).toBe(false); // var/local alone are not the dynamic markers
+  });
+});

package/src/terraform/graph.ts

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ */
+
+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`.
+ */
+const INTERPOLATION = /\$\{([^}]+)\}/g;
+
+/** `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"]);
+
+interface RawRef {
+  address: string;
+  attr?: 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] });
+  }
+  for (const m of expr.matchAll(DATA_REF)) {
+    refs.push({ address: `data.${m[1]}.${m[2]}`, attr: m[3] });
+  }
+  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] });
+  }
+  return refs;
+}
+
+/** Collect every `${...}` reference reachable in a block's value tree. */
+function refsInValue(value: unknown): 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]));
+    } 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);
+    }
+  };
+  visit(value);
+  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). */
+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];
+  if (typeof value !== "string" || value.includes("${")) return undefined;
+  return value;
+}
+
+/**
+ * Build the dependency graph from a merged hcl2json tree.
+ *
+ * `resource` and `module` blocks become nodes. `data` sources are NOT nodes
+ * (they are not carvable infrastructure), but a reference *to* a data source
+ * marks the referring node dynamic. An edge is recorded only when its target
+ * resolves to a known resource/module node — references to `var`/`local`/data
+ * are dropped.
+ */
+export function buildGraph(tree: Hcl2JsonTree): TfGraph {
+  const nodes: TfNode[] = [];
+  const dataAddresses = new Set<string>();
+
+  // First pass: register data-source addresses so refs to them can be spotted.
+  for (const [type, named] of Object.entries(tree.data ?? {})) {
+    for (const name of Object.keys(named)) dataAddresses.add(`data.${type}.${name}`);
+  }
+
+  // Resource nodes.
+  const rawRefsByNode = new Map<string, RawRef[]>();
+  for (const [type, named] of Object.entries(tree.resource ?? {})) {
+    for (const [name, blocks] of Object.entries(named)) {
+      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 touchesData = refs.some((r) => dataAddresses.has(r.address));
+      rawRefsByNode.set(address, refs);
+      nodes.push({
+        address,
+        kind: "resource",
+        type,
+        name,
+        instances: 1,
+        hasDynamic: dynamic || touchesData,
+        identity: literalIdentity(block, type),
+      });
+    }
+  }
+
+  // Module nodes.
+  for (const [name, blocks] of Object.entries(tree.module ?? {})) {
+    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 touchesData = refs.some((r) => dataAddresses.has(r.address));
+    rawRefsByNode.set(address, refs);
+    nodes.push({
+      address,
+      kind: "module",
+      name,
+      instances: 1,
+      hasDynamic: dynamic || touchesData,
+    });
+  }
+
+  // Edges: keep only references that resolve to a known node.
+  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>>();
+    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);
+    }
+    for (const [to, attrs] of byTarget) {
+      edges.push({ from, to, attrs: [...attrs].sort() });
+    }
+  }
+
+  // Code-point ordering (not localeCompare) so output is locale-independent and
+  // punctuation sorts predictably (`.` < `_`).
+  const cmp = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  return {
+    nodes: nodes.sort((a, b) => cmp(a.address, b.address)),
+    edges: edges.sort((a, b) => cmp(a.from, b.from) || cmp(a.to, b.to)),
+  };
+}
+
+/** Edges where other nodes depend on `address` (each → a surviving-TF data-source patch). */
+export function inboundEdges(graph: TfGraph, address: string): TfEdge[] {
+  return graph.edges.filter((e) => e.to === address);
+}
+
+/** Edges where `address` depends on other nodes (each → a deferred deploy-time input). */
+export function outboundEdges(graph: TfGraph, address: string): TfEdge[] {
+  return graph.edges.filter((e) => e.from === address);
+}

package/src/terraform/parse.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect, beforeAll } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { parseTerraformDir, loadHcl2json, Hcl2JsonNotInstalled } from "./parse";
+
+/**
+ * `@cdktf/hcl2json` is an optional (dev-only in this repo) dependency. These
+ * tests exercise the real wasm parser when it resolves and skip cleanly when it
+ * does not, so a consumer install without the parser never fails the suite.
+ */
+let parserAvailable = false;
+beforeAll(async () => {
+  try {
+    await loadHcl2json();
+    parserAvailable = true;
+  } catch {
+    parserAvailable = false;
+  }
+});
+
+describe("loadHcl2json", () => {
+  test("missing parser throws an install-hint error, not a raw MODULE_NOT_FOUND", () => {
+    const err = new Hcl2JsonNotInstalled(new Error("Cannot find module '@cdktf/hcl2json'"));
+    expect(err.message).toContain("npm install -D @cdktf/hcl2json");
+    expect(err.message).toContain("HCL parser");
+    expect(err.name).toBe("Hcl2JsonNotInstalled");
+  });
+});
+
+describe.runIf(true)("parseTerraformDir (real wasm)", () => {
+  test("parses a multi-file estate into the expected graph", async () => {
+    if (!parserAvailable) return; // optional dep absent — skip
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf-"));
+    try {
+      writeFileSync(
+        join(dir, "bucket.tf"),
+        `resource "aws_s3_bucket" "assets" {\n  bucket = "myapp-assets-prod"\n}\n`,
+      );
+      writeFileSync(
+        join(dir, "api.tf"),
+        `resource "aws_lambda_function" "api" {\n  environment {\n    variables = {\n      ASSETS_BUCKET = aws_s3_bucket.assets.bucket\n      ASSETS_ARN    = aws_s3_bucket.assets.arn\n    }\n  }\n}\n`,
+      );
+      const g = await parseTerraformDir(dir);
+      expect(g.nodes.map((n) => n.address)).toEqual([
+        "aws_lambda_function.api",
+        "aws_s3_bucket.assets",
+      ]);
+      expect(g.edges).toEqual([
+        { from: "aws_lambda_function.api", to: "aws_s3_bucket.assets", attrs: ["arn", "bucket"] },
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/terraform/parse.ts

@@ -0,0 +1,87 @@
+/**
+ * Thin wasm glue for the carve-out advisor (#214 T1): read a Terraform estate's
+ * `.tf` files, run them through `@cdktf/hcl2json`, merge into one tree, and hand
+ * off to the pure `buildGraph`.
+ *
+ * `@cdktf/hcl2json` is NOT a chant dependency — it carries a ~1.8 MB wasm blob
+ * and only carve-out users need it. It is lazy-loaded here and, if absent, the
+ * advisor fails with a one-line install hint.
+ */
+
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { buildGraph } 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>;
+
+export class Hcl2JsonNotInstalled extends Error {
+  constructor(cause: unknown) {
+    super(
+      "Terraform carve-out needs the HCL parser, which is not installed.\n" +
+        "  Install it once:  npm install -D @cdktf/hcl2json\n" +
+        `(underlying error: ${cause instanceof Error ? cause.message : String(cause)})`,
+    );
+    this.name = "Hcl2JsonNotInstalled";
+  }
+}
+
+/**
+ * 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> {
+  try {
+    const mod = (await import("@cdktf/hcl2json")) as { parse: Hcl2JsonParse };
+    return mod.parse;
+  } catch (err) {
+    throw new Hcl2JsonNotInstalled(err);
+  }
+}
+
+/** 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) {
+    const src = next[section];
+    if (!src) continue;
+    const dst = (into[section] ??= {}) as Record<string, Record<string, unknown[]>>;
+    for (const [type, named] of Object.entries(src)) {
+      dst[type] = { ...(dst[type] ?? {}), ...named };
+    }
+  }
+  if (next.module) into.module = { ...(into.module ?? {}), ...next.module };
+}
+
+/** List every `.tf` file directly under `dir` (non-recursive; matches Terraform's own module scoping). */
+function listTfFiles(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".tf"))
+    .map((f) => join(dir, f))
+    .sort();
+}
+
+export interface ParseTerraformOptions {
+  /** Opt-in `.tfstate` path (#214 T2): overlays state-expanded instance counts. */
+  statePath?: string;
+}
+
+/**
+ * Parse a Terraform directory into a dependency graph. Reads only `.tf` unless
+ * `statePath` is given. Pure `.tf` estates parse fully; `count`/`for_each`
+ * blocks report a single instance and are flagged `hasDynamic`. With state, the
+ * instance counts become accurate (see `state.ts`).
+ */
+export async function parseTerraformDir(dir: string, opts: ParseTerraformOptions = {}): Promise<TfGraph> {
+  const parse = await loadHcl2json();
+  const files = listTfFiles(dir);
+  const merged: Hcl2JsonTree = {};
+  for (const file of files) {
+    const tree = await parse(file, readFileSync(file, "utf-8"));
+    mergeTrees(merged, tree);
+  }
+  const graph = buildGraph(merged);
+  if (opts.statePath) applyStateCounts(graph, readStateInstanceCounts(opts.statePath));
+  return graph;
+}