@intentius/chant 0.61.0 → 0.63.0

package/src/runtime-adapter.ts

@@ -40,7 +40,14 @@ export interface RuntimeAdapter {
    * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
    * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
    */
-  spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult>;
+  /**
+   * `opts.env` merges over the parent environment rather than replacing it —
+   * a caller pinning `LC_ALL=C` to parse a command's output must not also
+   * have to reconstruct `PATH`, `HOME` and everything else the child needs.
+   * An entry whose value is `""` is passed through as empty, which is how a
+   * gettext override like `LANGUAGE` is neutralised.
+   */
+  spawn(cmd: string[], opts?: { cwd?: string; stdin?: string; env?: Record<string, string> }): Promise<SpawnResult>;
   /** Commands to use when spawning package manager / executor */
   readonly commands: RuntimeCommands;
 }
@@ -64,12 +71,19 @@ class NodeRuntimeAdapter implements RuntimeAdapter {
     return picomatch(pattern)(filePath);
   }
 
-  async spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult> {
+  async spawn(
+    cmd: string[],
+    opts?: { cwd?: string; stdin?: string; env?: Record<string, string> },
+  ): Promise<SpawnResult> {
     return new Promise((resolve) => {
       const child = execFile(
         cmd[0],
         cmd.slice(1),
-        { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 },
+        {
+          cwd: opts?.cwd,
+          maxBuffer: 10 * 1024 * 1024,
+          ...(opts?.env ? { env: { ...process.env, ...opts.env } } : {}),
+        },
         (err, stdout, stderr) => {
           resolve({
             stdout: stdout ?? "",

package/src/terraform/__fixtures__/build-graph.ts

@@ -1,6 +1,48 @@
 import { buildGraph, collectExpressions, type ExpressionRefs } from "../graph";
 import type { Hcl2JsonTree, TfGraph } from "../types";
 
+/**
+ * Shortest-hop count from `address` back through inbound edges — how many
+ * dependents-of-dependents deep the estate goes behind that node (#2323).
+ * Production has no reachability pass yet (that is the spike's sub-issue 3);
+ * this is a test-only BFS over the same `TfGraph` shape, so a fixture's depth
+ * can be asserted without waiting on that feature. Folds/outputs are not
+ * special-cased: an output pseudo-address has no inbound edges by
+ * construction (`buildGraph` never lets anything reference an output), so it
+ * is always a dead end and never inflates the count.
+ */
+function inboundDepthOf(graph: TfGraph, address: string): number {
+  let frontier = new Set([address]);
+  const visited = new Set(frontier);
+  let depth = 0;
+  for (;;) {
+    const next = new Set<string>();
+    for (const e of graph.edges) {
+      if (frontier.has(e.to) && !visited.has(e.from)) next.add(e.from);
+    }
+    if (next.size === 0) return depth;
+    depth++;
+    for (const addr of next) visited.add(addr);
+    frontier = next;
+  }
+}
+
+/**
+ * The longest inbound chain anywhere in the graph — the same "depth" column
+ * the spike measured (docs/design/carve-dependency-blast-radius-spike.md
+ * section 2): 1 hop is a direct dependent, 2 is a dependent of a dependent,
+ * and so on. Every shipped fixture tops out at 1; `depth-estate` is built to
+ * clear that.
+ */
+export function maxTransitiveInboundDepth(graph: TfGraph): number {
+  let max = 0;
+  for (const node of graph.nodes) {
+    const depth = inboundDepthOf(graph, node.address);
+    if (depth > max) max = depth;
+  }
+  return max;
+}
+
 /**
  * Test-only stand-in for the hcl2json expression AST (`parse.ts`'s
  * `resolveExpressionRefs`). Fixture expressions are simple `${<accessor>}`

package/src/terraform/__fixtures__/carve-locals-data.test.ts

@@ -0,0 +1,138 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveAdvise, carveJson } from "../../cli/commands/carve";
+import { carveBridge } from "../../cli/commands/carve-bridge";
+import { loadHcl2json } from "../parse";
+
+/**
+ * The three-route estate from the blast-radius spike (#2324), through the real
+ * wasm parser: one bucket with three dependents, one reading it directly, one
+ * through a `locals` block and one through a `data` source. The advisor used to
+ * report a single dependent and band the bucket a clean leaf, and `carve bridge`
+ * left the other two routes pointing at a resource Terraform no longer manages.
+ *
+ * Skips cleanly when the optional parser is absent, like the other estate tests.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `resource "aws_s3_bucket" "assets" {
+  bucket = "app-assets"
+}
+
+locals {
+  assets_id = aws_s3_bucket.assets.id
+}
+
+resource "aws_lambda_function" "via_local" {
+  function_name = "via-local"
+  environment { variables = { B = local.assets_id } }
+}
+
+data "aws_s3_bucket" "lookup" {
+  bucket = aws_s3_bucket.assets.bucket
+}
+
+resource "aws_lambda_function" "via_data" {
+  function_name = "via-data"
+  environment { variables = { B = data.aws_s3_bucket.lookup.arn } }
+}
+
+resource "aws_lambda_function" "direct" {
+  function_name = "direct"
+  environment { variables = { B = aws_s3_bucket.assets.arn } }
+}
+`;
+
+/**
+ * The same estate with the direct reference taken out, so every remaining route
+ * to the bucket runs through a referrer. This is the case that actually breaks:
+ * with no direct reference the advisor found no inbound edge at all, so
+ * `carve bridge` generated no data source and rewrote nothing, and the excised
+ * bucket left two dangling references behind.
+ */
+const INDIRECT_ONLY = ESTATE.split('resource "aws_lambda_function" "direct"')[0];
+
+async function withEstate<T>(source: string, fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-2324-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), source);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("dependencies reached through locals and data blocks", () => {
+  test("the advisor counts all three dependents, not just the direct one", async () => {
+    if (!parserAvailable) return;
+    await withEstate(ESTATE, async (dir) => {
+      const report = carveJson(await carveAdvise({ from: dir }));
+      const bucket = report.resources.find((r) => r.address === "aws_s3_bucket.assets")!;
+
+      expect(bucket.breakdown.inbound).toBe(3);
+      expect(bucket.boundary!.inbound.map((e) => e.survivor)).toEqual([
+        "aws_lambda_function.direct",
+        "aws_lambda_function.via_data",
+        "aws_lambda_function.via_local",
+      ]);
+
+      // Three dependents at -12 each: no longer the top band on a third of the truth.
+      expect(bucket.score).toBe(64);
+      expect(bucket.band).toBe("carvable w/ edits");
+    });
+  });
+
+  test("carve bridge rewires the locals and data routes, not only the direct one", async () => {
+    if (!parserAvailable) return;
+    await withEstate(ESTATE, async (dir) => {
+      const bridge = await carveBridge({
+        from: dir,
+        select: "aws_s3_bucket.assets",
+        output: join(dir, "carveout"),
+      });
+      expect(bridge.ok).toBe(true);
+
+      const rewritten = bridge.plan!.rewrites.find((r) => r.changed)!.rewritten;
+      // Every reference to the carved bucket now goes through the data source...
+      expect(rewritten).toContain("assets_id = data.aws_s3_bucket.assets.id");
+      expect(rewritten).toContain("bucket = data.aws_s3_bucket.assets.bucket");
+      expect(rewritten).toContain("B = data.aws_s3_bucket.assets.arn");
+      expect(rewritten).not.toMatch(/(?<!data\.)aws_s3_bucket\.assets\./);
+      // ...and the carved block itself is gone, so the next apply cannot re-create it.
+      expect(bridge.plan!.excised).toEqual(["aws_s3_bucket.assets"]);
+
+      // The two indirect readers are untouched: their own references were never
+      // to the bucket, and the referrers they read through still resolve.
+      expect(rewritten).toContain("B = local.assets_id");
+      expect(rewritten).toContain("B = data.aws_s3_bucket.lookup.arn");
+    });
+  });
+
+  test("an estate whose only routes are indirect still gets a data source and a rewrite", async () => {
+    if (!parserAvailable) return;
+    await withEstate(INDIRECT_ONLY, async (dir) => {
+      const bridge = await carveBridge({
+        from: dir,
+        select: "aws_s3_bucket.assets",
+        output: join(dir, "carveout"),
+      });
+      expect(bridge.ok).toBe(true);
+
+      // Without an inbound edge there is no data source to rewrite references
+      // to, and the excised bucket leaves the locals and data bodies dangling.
+      expect(bridge.plan!.dataSources.map((d) => d.address)).toEqual(["aws_s3_bucket.assets"]);
+      const rewritten = bridge.plan!.rewrites.find((r) => r.changed)!.rewritten;
+      expect(rewritten).toContain("assets_id = data.aws_s3_bucket.assets.id");
+      expect(rewritten).toContain("bucket = data.aws_s3_bucket.assets.bucket");
+      expect(rewritten).not.toMatch(/(?<!data\.)aws_s3_bucket\.assets\./);
+    });
+  });
+});

package/src/terraform/__fixtures__/depth-estate/main.tf

@@ -0,0 +1,141 @@
+# A Terraform estate built to close the gaps the carve dependency/blast-radius
+# spike found in every other fixture (docs/design/carve-dependency-blast-
+# radius-spike.md, #2323): none of them has a two-hop dependency chain, and
+# none has a `depends_on` edge. Every resource below carries a comment saying
+# which of those gaps it demonstrates; several are lifted verbatim from the
+# spike's appendix, which lacked the `depends_on`, `count` and module cases
+# folded in here.
+
+# --- The depth chain: vpc -> subnet -> db_subnet_group -> rds_cluster -> instance ---
+# aws_vpc.main sits three inbound hops upstream of aws_rds_cluster_instance.one
+# (vpc -> subnet.a -> db_subnet_group.main -> rds_cluster.main -> instance/
+# lambda), the transitive chain no shipped fixture has. Every other fixture's
+# max transitive inbound depth is 1.
+resource "aws_vpc" "main" {
+  cidr_block = "10.0.0.0/16"
+}
+
+resource "aws_subnet" "a" {
+  vpc_id     = aws_vpc.main.id
+  cidr_block = "10.0.1.0/24"
+}
+
+resource "aws_subnet" "b" {
+  vpc_id     = aws_vpc.main.id
+  cidr_block = "10.0.2.0/24"
+}
+
+# count: without `--state`, `applyStateCounts` never runs, so a `.tf`-only
+# parse reports 1 instance here and flags `hasDynamic`. The shipped
+# terraform.tfstate resolves it to 3, so the fixture also exercises
+# `readStateInstanceCounts`/`applyStateCounts` when advised with `--state`.
+resource "aws_subnet" "private" {
+  count      = 3
+  vpc_id     = aws_vpc.main.id
+  cidr_block = "10.1.${count.index}.0/24"
+}
+
+resource "aws_security_group" "db" {
+  vpc_id = aws_vpc.main.id
+  name   = "db"
+}
+
+resource "aws_security_group" "app" {
+  vpc_id = aws_vpc.main.id
+  name   = "app"
+}
+
+resource "aws_db_subnet_group" "main" {
+  name       = "main"
+  subnet_ids = [aws_subnet.a.id, aws_subnet.b.id]
+}
+
+resource "aws_kms_key" "data" {
+  description = "rds + s3"
+}
+
+resource "aws_rds_cluster" "main" {
+  cluster_identifier     = "app-db"
+  db_subnet_group_name   = aws_db_subnet_group.main.name
+  vpc_security_group_ids = [aws_security_group.db.id]
+  kms_key_id             = aws_kms_key.data.arn
+}
+
+# Leave in Terraform: no native mapping (score 0), and the far end of the
+# depth chain above — the node the whole fixture exists to put three hops
+# behind aws_vpc.main.
+resource "aws_rds_cluster_instance" "one" {
+  identifier         = "app-db-1"
+  cluster_identifier = aws_rds_cluster.main.id
+}
+
+# --- A second, shorter chain off the same VPC: lb -> target group -> listener ---
+resource "aws_lb" "public" {
+  name    = "app-lb"
+  subnets = [aws_subnet.a.id, aws_subnet.b.id]
+}
+
+resource "aws_lb_target_group" "app" {
+  name   = "app-tg"
+  port   = 8080
+  vpc_id = aws_vpc.main.id
+}
+
+resource "aws_lb_listener" "https" {
+  load_balancer_arn = aws_lb.public.arn
+  port              = 443
+  default_action {
+    target_group_arn = aws_lb_target_group.app.arn
+    type             = "forward"
+  }
+}
+
+# Clean leaf: a bucket a Lambda reads from. Its versioning sub-resource folds
+# into it (same shape as `sample-estate`) and is never ranked on its own.
+resource "aws_s3_bucket" "assets" {
+  bucket = "app-assets"
+}
+
+resource "aws_s3_bucket_versioning" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+# depends_on: nothing below reads an attribute off this log group, but the
+# Lambda names it in `depends_on` — a real pattern (ordering a function's log
+# group ahead of the function). hcl2json renders `depends_on =
+# [aws_cloudwatch_log_group.api]` as the interpolation
+# "${aws_cloudwatch_log_group.api}", which `refsInBlock` already picks up with
+# `via: ["depends_on"]` and no attribute; nothing in the fixture corpus
+# exercised it before this estate.
+resource "aws_cloudwatch_log_group" "api" {
+  name              = "/myapp/api"
+  retention_in_days = 30
+}
+
+resource "aws_lambda_function" "api" {
+  function_name = "app-api"
+  kms_key_arn   = aws_kms_key.data.arn
+  depends_on    = [aws_cloudwatch_log_group.api]
+  environment {
+    variables = {
+      ASSETS = aws_s3_bucket.assets.bucket
+      DB     = aws_rds_cluster.main.endpoint
+      SG     = aws_security_group.app.id
+    }
+  }
+}
+
+# module: a module block is one graph node whatever it contains — state is
+# read for root-module resources only, so radius through a module undercounts
+# by however much the module holds. No other fixture has one.
+module "platform" {
+  source     = "./modules/platform"
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = [aws_subnet.a.id, aws_subnet.b.id]
+}
+
+output "lb_dns"      { value = aws_lb.public.dns_name }
+output "db_endpoint" { value = aws_rds_cluster.main.endpoint }

package/src/terraform/__fixtures__/depth-estate/terraform.tfstate

@@ -0,0 +1,17 @@
+{
+  "version": 4,
+  "terraform_version": "1.7.0",
+  "resources": [
+    {
+      "mode": "managed",
+      "type": "aws_subnet",
+      "name": "private",
+      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
+      "instances": [
+        { "attributes": { "id": "subnet-priv-0", "cidr_block": "10.1.0.0/24" } },
+        { "attributes": { "id": "subnet-priv-1", "cidr_block": "10.1.1.0/24" } },
+        { "attributes": { "id": "subnet-priv-2", "cidr_block": "10.1.2.0/24" } }
+      ]
+    }
+  ]
+}

package/src/terraform/__fixtures__/depth-estate.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect } from "vitest";
+import { join } from "path";
+import { carveAdvise, carveJson, type CarveJsonResource } from "../../cli/commands/carve";
+import { loadHcl2json, parseTerraformDir } from "../parse";
+import { maxTransitiveInboundDepth } from "./build-graph";
+
+/**
+ * `depth-estate` (#2323) closes the gap the carve dependency/blast-radius
+ * spike found: every shipped fixture — `sample-estate`, `gcp-estate`, the
+ * carve-out examples, the CDK fixture — has a max transitive inbound depth of
+ * 1 and no `depends_on` edge (docs/design/carve-dependency-blast-radius-spike.md
+ * section 2). A future transitive-reachability implementation would pass the
+ * whole existing suite whether it were correct, inverted, or a stub returning
+ * the direct count. This estate has a real chain, a `depends_on` edge, a
+ * `count` block and a module, so it can't.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "depth-estate");
+const STATE = join(ESTATE, "terraform.tfstate");
+
+describe("the depth-estate fixture actually has depth", () => {
+  test("max transitive inbound depth is 3, not the 1 every other fixture tops out at", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+
+    // The guard that matters: a snapshot alone can't tell a flat estate from
+    // one with real depth, so this is asserted directly against the graph the
+    // production parse path builds — not against the pinned scores below,
+    // which would still pass at depth 1.
+    const depth = maxTransitiveInboundDepth(graph);
+    expect(depth).toBeGreaterThan(1);
+    // Pinned to the exact chain the fixture was built around: aws_vpc.main ->
+    // aws_subnet.a -> aws_db_subnet_group.main -> aws_rds_cluster.main ->
+    // {aws_rds_cluster_instance.one, aws_lambda_function.api}, 3 inbound hops.
+    expect(depth).toBe(3);
+  });
+});
+
+describe("carve advise against depth-estate", () => {
+  test("bands the chain, the depends_on edge, the count block and the module", async () => {
+    if (!parserAvailable) return;
+    const r = await carveAdvise({ from: ESTATE });
+    expect(r.ok).toBe(true);
+    const byAddr = Object.fromEntries((r.results ?? []).map((x) => [x.address, x]));
+
+    // The root of the depth chain: 7 direct inbound edges (2 subnets, the
+    // count-expanded subnet, 2 security groups, the target group, the
+    // module), no tier penalty (aws_vpc is tier 1).
+    expect(byAddr["aws_vpc.main"].band).toBe("leave in Terraform");
+    expect(byAddr["aws_vpc.main"].score).toBe(16); // 100 - 12*7
+    expect(byAddr["aws_vpc.main"].breakdown.inbound).toBe(7);
+
+    // One hop down: a data-source patch each for the db subnet group and the
+    // load balancer, both of which read it directly.
+    expect(byAddr["aws_subnet.a"].band).toBe("carvable w/ edits");
+    expect(byAddr["aws_subnet.a"].score).toBe(60); // 100 - 12*3 - 4*1
+
+    // The far end of the chain: no native mapping, so it scores 0 regardless
+    // of how deep it sits.
+    expect(byAddr["aws_rds_cluster_instance.one"].score).toBe(0);
+    expect(byAddr["aws_rds_cluster_instance.one"].band).toBe("leave in Terraform");
+
+    // depends_on: the log group carries no attribute reference from the
+    // Lambda, only a bare `depends_on` — and still counts as one inbound edge
+    // (#2323's second gap, real since hcl2json but untested until this).
+    expect(byAddr["aws_cloudwatch_log_group.api"].band).toBe("clean leaf");
+    expect(byAddr["aws_cloudwatch_log_group.api"].score).toBe(88); // 100 - 12*1
+    expect(byAddr["aws_cloudwatch_log_group.api"].breakdown.inbound).toBe(1);
+
+    // count: a `.tf`-only parse can't know the fan-out, so it stays at 1
+    // instance and gets the flat -10 `hasDynamic` penalty rather than an
+    // instances penalty.
+    expect(byAddr["aws_subnet.private"].breakdown.hasDynamic).toBe(true);
+    expect(byAddr["aws_subnet.private"].breakdown.instances).toBe(1);
+    expect(byAddr["aws_subnet.private"].score).toBe(86); // 100 - 4*1(outbound) - 10(dynamic)
+
+    // module: one node regardless of what it holds, tier 2 (a chant
+    // composite reshapes), 3 outbound edges for the vpc_id and subnet_ids
+    // inputs it takes.
+    expect(byAddr["module.platform"].kind).toBe("module");
+    expect(byAddr["module.platform"].breakdown.outbound).toBe(3);
+    expect(byAddr["module.platform"].score).toBe(73); // 100 - 4*3 - 15
+
+    // The report never proposes a mutation.
+    expect((r.results ?? []).length).toBeGreaterThan(0);
+  });
+
+  test("the depends_on edge round-trips through the JSON boundary report from both ends", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+    const byAddr = Object.fromEntries(report.resources.map((x) => [x.address, x]));
+
+    // Seen from the survivor: an inbound edge with no attrs, via depends_on,
+    // bridged the same as any other inbound cut (a data-source patch).
+    expect(byAddr["aws_cloudwatch_log_group.api"].boundary).toEqual({
+      inbound: [
+        {
+          direction: "inbound",
+          survivor: "aws_lambda_function.api",
+          carved: "aws_cloudwatch_log_group.api",
+          attrs: [],
+          via: ["depends_on"],
+          bridge: "tf-data-source",
+          required: "immediately",
+        },
+      ],
+      outbound: [],
+    });
+
+    // Seen from the depending side: the same edge, now a deferred input.
+    const lambdaOut = byAddr["aws_lambda_function.api"].boundary!.outbound;
+    expect(lambdaOut).toContainEqual({
+      direction: "outbound",
+      survivor: "aws_cloudwatch_log_group.api",
+      carved: "aws_lambda_function.api",
+      attrs: [],
+      via: ["depends_on"],
+      bridge: "deferred-input",
+      required: "at-apply",
+    });
+  });
+
+  const allEdges = (resources: CarveJsonResource[]) =>
+    resources.flatMap((r) => [...(r.boundary?.inbound ?? []), ...(r.boundary?.outbound ?? [])]);
+
+  test("every edge endpoint is a real address in the estate, module included", async () => {
+    if (!parserAvailable) return;
+    const report = carveJson(await carveAdvise({ from: ESTATE }));
+    const ranked = new Set(report.resources.map((r) => r.address));
+    for (const edge of allEdges(report.resources)) {
+      expect(ranked.has(edge.carved)).toBe(true);
+      expect(edge.survivor).not.toBe(edge.carved);
+    }
+    expect(ranked.has("module.platform")).toBe(true);
+  });
+});
+
+describe("carve advise --state against depth-estate", () => {
+  test("resolves the count block's real fan-out, on top of the flat hasDynamic penalty", async () => {
+    if (!parserAvailable) return;
+    const r = await carveAdvise({ from: ESTATE, statePath: STATE });
+    expect(r.ok).toBe(true);
+    const byAddr = Object.fromEntries((r.results ?? []).map((x) => [x.address, x]));
+
+    // `readStateInstanceCounts`/`applyStateCounts` only run with `--state`
+    // (state.ts:64,:81) — the shipped terraform.tfstate resolves the 3
+    // instances the .tf-only parse above could not see. `hasDynamic` stays
+    // true (state doesn't erase that it's a count block); the instances
+    // penalty now also applies.
+    expect(byAddr["aws_subnet.private"].breakdown.instances).toBe(3);
+    expect(byAddr["aws_subnet.private"].breakdown.hasDynamic).toBe(true);
+    expect(byAddr["aws_subnet.private"].score).toBe(80); // 100 - 4*1 - 10 - 3*2
+    expect(byAddr["aws_subnet.private"].breakdown.penalties.instances).toBe(-6);
+  });
+});