@intentius/chant 0.18.37 → 0.19.1

package/src/terraform/score.test.ts

@@ -0,0 +1,140 @@
+import { describe, test, expect } from "vitest";
+import { buildGraph } from "./graph";
+import { scoreEstate, bandFor } from "./score";
+import type { Hcl2JsonTree } from "./types";
+
+const byAddress = (results: ReturnType<typeof scoreEstate>) =>
+  Object.fromEntries(results.map((r) => [r.address, r]));
+
+describe("scoreEstate — #197 worked examples", () => {
+  test("clean leaf: aws_s3_bucket.assets ≈ 88 (versioning folded, 1 inbound from Lambda)", () => {
+    const tree: 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}",
+                },
+              },
+            },
+          ],
+        },
+      },
+    };
+    const results = scoreEstate(buildGraph(tree));
+    const map = byAddress(results);
+
+    // The folded sub-resource is not ranked on its own.
+    expect(map["aws_s3_bucket_versioning.assets"]).toBeUndefined();
+
+    const bucket = map["aws_s3_bucket.assets"];
+    expect(bucket.score).toBe(88); // 100 - 12*1(inbound) ; versioning edge discounted
+    expect(bucket.band).toBe("clean leaf");
+    expect(bucket.mapsTo).toBe("AWS::S3::Bucket");
+    expect(bucket.breakdown.inbound).toBe(1);
+  });
+
+  test("carvable w/ edits: module.cdn ≈ 61 (2 inbound, tier-2 composite map)", () => {
+    const tree: Hcl2JsonTree = {
+      module: { cdn: [{ source: "./cdn" }] },
+      resource: {
+        aws_route53_record: {
+          www: [{ name: "${module.cdn.domain}" }],
+          apex: [{ name: "${module.cdn.domain}" }],
+        },
+      },
+    };
+    const results = scoreEstate(buildGraph(tree));
+    const cdn = byAddress(results)["module.cdn"];
+    expect(cdn.score).toBe(61); // 100 - 12*2 - 15*(2-1)
+    expect(cdn.band).toBe("carvable w/ edits");
+    expect(cdn.breakdown.inbound).toBe(2);
+    expect(cdn.breakdown.tier).toBe(2);
+  });
+
+  test("leave in Terraform: aws_vpc.main with 40 inbound → clamped to 0", () => {
+    const consumers: Record<string, unknown[]> = {};
+    for (let i = 0; i < 40; i++) {
+      consumers[`s${i}`] = [{ vpc_id: "${aws_vpc.main.id}" }];
+    }
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_vpc: { main: [{ cidr_block: "10.0.0.0/16" }] },
+        aws_subnet: consumers,
+      },
+    };
+    const vpc = byAddress(scoreEstate(buildGraph(tree)))["aws_vpc.main"];
+    expect(vpc.score).toBe(0);
+    expect(vpc.band).toBe("leave in Terraform");
+    expect(vpc.breakdown.inbound).toBe(40);
+  });
+});
+
+describe("scoreEstate — penalties", () => {
+  test("unsupported provider/type scores 0 regardless of edges", () => {
+    const tree: Hcl2JsonTree = {
+      resource: { random_pet: { name: [{ length: 2 }] } },
+    };
+    const r = scoreEstate(buildGraph(tree))[0];
+    expect(r.score).toBe(0);
+    expect(r.breakdown.tier).toBeNull();
+    expect(r.mapsTo).toBeUndefined();
+  });
+
+  test("count/for_each applies the dynamic penalty", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sqs_queue: {
+          plain: [{ name: "q" }],
+          fanned: [{ count: 3, name: "q" }],
+        },
+      },
+    };
+    const map = byAddress(scoreEstate(buildGraph(tree)));
+    expect(map["aws_sqs_queue.plain"].score).toBe(100); // tier1, no edges, no dynamic
+    expect(map["aws_sqs_queue.fanned"].score).toBe(90); // -10 dynamic
+  });
+
+  test("outbound dependency costs less than inbound", () => {
+    // A tier-1 leaf that depends on one survivor: -4 outbound.
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_sns_topic: { alerts: [{ name: "a" }] },
+        aws_sqs_queue: { dlq: [{ name: "d", redrive: "${aws_sns_topic.alerts.arn}" }] },
+      },
+    };
+    const map = byAddress(scoreEstate(buildGraph(tree)));
+    expect(map["aws_sqs_queue.dlq"].score).toBe(96); // 100 - 4*1 outbound
+    expect(map["aws_sns_topic.alerts"].score).toBe(88); // 100 - 12*1 inbound
+  });
+
+  test("results are ranked most-peelable first", () => {
+    const tree: Hcl2JsonTree = {
+      resource: {
+        aws_vpc: { main: [{ cidr_block: "10.0.0.0/16" }] },
+        aws_sqs_queue: { q: [{ name: "q", vpc: "${aws_vpc.main.id}" }] },
+        aws_sns_topic: { t: [{ name: "t" }] },
+      },
+    };
+    const scores = scoreEstate(buildGraph(tree)).map((r) => r.score);
+    expect(scores).toEqual([...scores].sort((a, b) => b - a));
+  });
+});
+
+describe("bandFor", () => {
+  test("band boundaries", () => {
+    expect(bandFor(100)).toBe("clean leaf");
+    expect(bandFor(80)).toBe("clean leaf");
+    expect(bandFor(79)).toBe("carvable w/ edits");
+    expect(bandFor(50)).toBe("carvable w/ edits");
+    expect(bandFor(49)).toBe("leave in Terraform");
+    expect(bandFor(0)).toBe("leave in Terraform");
+  });
+});

package/src/terraform/score.ts

@@ -0,0 +1,148 @@
+/**
+ * Peelability scoring for the carve-out advisor (#214 T3).
+ *
+ * The model, verbatim from #197:
+ *
+ *   score = 100
+ *     - 12 * inbound          # survivors that depend on this → each a TF data-source patch
+ *     -  4 * outbound         # this depends on survivors → a deferred deploy-time input
+ *     - 15 * (tier - 1)       # native-spec map: tier1=0, tier2=-15, tier3=-30
+ *     - 10 * has_dynamic      # count / for_each / data present
+ *     -  3 * (instances - 1)  # state-expanded instance count
+ *   clamp 0..100   (unsupported provider/type → 0)
+ *
+ * Sub-resources that inline into a parent (see `FOLDS_INTO`) are folded into the
+ * parent's carve set: they are removed from the ranking and their edge to the
+ * parent is not counted as inbound — inlining them is free, not boundary work.
+ */
+
+import { inboundEdges, outboundEdges } from "./graph";
+import { FOLDS_INTO, resolveTier } from "./tier-map";
+import type { TfGraph, TfNode } from "./types";
+
+export type PeelabilityBand = "clean leaf" | "carvable w/ edits" | "leave in Terraform";
+
+export interface PeelabilityBreakdown {
+  inbound: number;
+  outbound: number;
+  tier: 1 | 2 | 3 | null;
+  hasDynamic: boolean;
+  instances: number;
+  /** Signed penalty contributions, for report transparency. */
+  penalties: {
+    inbound: number;
+    outbound: number;
+    tier: number;
+    dynamic: number;
+    instances: number;
+  };
+}
+
+export interface Peelability {
+  address: string;
+  kind: "resource" | "module";
+  score: number;
+  band: PeelabilityBand;
+  /** Native spec type a carve would target; undefined for modules/unsupported. */
+  mapsTo?: string;
+  breakdown: PeelabilityBreakdown;
+}
+
+const clamp = (n: number): number => Math.max(0, Math.min(100, n));
+
+export function bandFor(score: number): PeelabilityBand {
+  if (score >= 80) return "clean leaf";
+  if (score >= 50) return "carvable w/ edits";
+  return "leave in Terraform";
+}
+
+/** Module tier: a module maps to a chant composite — reshaping, so tier 2 by default. */
+const MODULE_TIER = 2 as const;
+
+/**
+ * Build the set of addresses that fold into a parent present in the estate, plus
+ * the reverse lookup (parent → its folded children), so a parent can discount
+ * inbound edges coming from its own folded sub-resources.
+ */
+function computeFolds(graph: TfGraph): { folded: Set<string>; childrenOf: Map<string, Set<string>> } {
+  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+  const folded = new Set<string>();
+  const childrenOf = new Map<string, Set<string>>();
+  for (const node of graph.nodes) {
+    if (node.kind !== "resource" || !node.type) continue;
+    const parentType = FOLDS_INTO[node.type];
+    if (!parentType) continue;
+    const parentAddress = `${parentType}.${node.name}`;
+    if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
+    folded.add(node.address);
+    if (!childrenOf.has(parentAddress)) childrenOf.set(parentAddress, new Set());
+    childrenOf.get(parentAddress)!.add(node.address);
+  }
+  return { folded, childrenOf };
+}
+
+function scoreNode(node: TfNode, graph: TfGraph, foldedChildren: Set<string>): Peelability {
+  // Inbound excludes edges from this node's own folded sub-resources.
+  const inbound = inboundEdges(graph, node.address).filter((e) => !foldedChildren.has(e.from)).length;
+  const outbound = outboundEdges(graph, node.address).length;
+
+  const tierInfo = node.kind === "module" ? { tier: MODULE_TIER, mapsTo: undefined } : resolveTier(node.type!);
+  const tier = tierInfo ? tierInfo.tier : null;
+
+  // Unsupported provider/type → 0, no partial credit.
+  if (tier === null) {
+    return {
+      address: node.address,
+      kind: node.kind,
+      score: 0,
+      band: "leave in Terraform",
+      breakdown: {
+        inbound,
+        outbound,
+        tier: null,
+        hasDynamic: node.hasDynamic,
+        instances: node.instances,
+        penalties: { inbound: 0, outbound: 0, tier: 0, dynamic: 0, instances: 0 },
+      },
+    };
+  }
+
+  const penalties = {
+    inbound: -12 * inbound,
+    outbound: -4 * outbound,
+    tier: -15 * (tier - 1),
+    dynamic: node.hasDynamic ? -10 : 0,
+    instances: -3 * Math.max(0, node.instances - 1),
+  };
+  const score = clamp(
+    100 + penalties.inbound + penalties.outbound + penalties.tier + penalties.dynamic + penalties.instances,
+  );
+
+  return {
+    address: node.address,
+    kind: node.kind,
+    score,
+    band: bandFor(score),
+    mapsTo: tierInfo && "mapsTo" in tierInfo ? tierInfo.mapsTo : undefined,
+    breakdown: {
+      inbound,
+      outbound,
+      tier,
+      hasDynamic: node.hasDynamic,
+      instances: node.instances,
+      penalties,
+    },
+  };
+}
+
+/**
+ * Score every carvable node in the estate, ranked most-peelable first. Folded
+ * sub-resources are omitted (they carve with their parent, not on their own).
+ */
+export function scoreEstate(graph: TfGraph): Peelability[] {
+  const { folded, childrenOf } = computeFolds(graph);
+  return graph.nodes
+    .filter((n) => !folded.has(n.address))
+    .map((n) => scoreNode(n, graph, childrenOf.get(n.address) ?? new Set()))
+    .sort((a, b) => b.score - a.score || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+}

package/src/terraform/state.test.ts

@@ -0,0 +1,76 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { readStateInstanceCounts, applyStateCounts } from "./state";
+import { buildGraph } from "./graph";
+import { scoreEstate } from "./score";
+import type { Hcl2JsonTree } from "./types";
+
+function withState<T>(state: unknown, fn: (path: string) => T): T {
+  const dir = mkdtempSync(join(tmpdir(), "chant-tfstate-"));
+  const path = join(dir, "terraform.tfstate");
+  try {
+    writeFileSync(path, JSON.stringify(state));
+    return fn(path);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const STATE = {
+  version: 4,
+  resources: [
+    { mode: "managed", type: "aws_instance", name: "web", instances: [{}, {}, {}] },
+    { mode: "managed", type: "aws_sqs_queue", name: "solo", instances: [{}] },
+    // data source — ignored
+    { mode: "data", type: "aws_ami", name: "ubuntu", instances: [{}] },
+    // nested in a module — no top-level node, ignored
+    { module: "module.cdn", mode: "managed", type: "aws_s3_bucket", name: "logs", instances: [{}, {}] },
+  ],
+};
+
+describe("readStateInstanceCounts", () => {
+  test("counts root-module managed instances, skips data + module-nested", () => {
+    withState(STATE, (path) => {
+      const counts = readStateInstanceCounts(path);
+      expect(counts.get("aws_instance.web")).toBe(3);
+      expect(counts.get("aws_sqs_queue.solo")).toBe(1);
+      expect(counts.has("aws_ami.ubuntu")).toBe(false); // data source
+      expect(counts.has("aws_s3_bucket.logs")).toBe(false); // module-nested
+    });
+  });
+});
+
+describe("applyStateCounts", () => {
+  test("overlays counts; nodes absent from state keep 1", () => {
+    const graph = buildGraph({
+      resource: {
+        aws_instance: { web: [{ count: 3, ami: "x" }] },
+        aws_sqs_queue: { orphan: [{ name: "q" }] },
+      },
+    } as Hcl2JsonTree);
+    applyStateCounts(graph, new Map([["aws_instance.web", 3]]));
+    const byAddr = Object.fromEntries(graph.nodes.map((n) => [n.address, n]));
+    expect(byAddr["aws_instance.web"].instances).toBe(3);
+    expect(byAddr["aws_sqs_queue.orphan"].instances).toBe(1);
+  });
+
+  test("state-accurate fan-out lowers peelability via the instances penalty", () => {
+    const tree: Hcl2JsonTree = {
+      resource: { aws_sqs_queue: { fan: [{ count: 5, name: "q" }] } },
+    };
+    // Without state: instances=1, only the -10 dynamic penalty → 90.
+    const noState = scoreEstate(buildGraph(tree))[0];
+    expect(noState.score).toBe(90);
+    expect(noState.breakdown.instances).toBe(1);
+
+    // With state: 5 instances → -10 dynamic -3*(5-1)=-12 → 78, drops out of "clean leaf".
+    const withCounts = buildGraph(tree);
+    applyStateCounts(withCounts, new Map([["aws_sqs_queue.fan", 5]]));
+    const stated = scoreEstate(withCounts)[0];
+    expect(stated.breakdown.instances).toBe(5);
+    expect(stated.score).toBe(78);
+    expect(stated.band).toBe("carvable w/ edits");
+  });
+});

package/src/terraform/state.ts

@@ -0,0 +1,87 @@
+/**
+ * Opt-in `.tfstate` reader for the carve-out advisor (#214 T2).
+ *
+ * A `.tf`-only parse cannot know how many instances a `count`/`for_each` block
+ * expands to — it reports 1 and flags the node dynamic. State is where those
+ * are unrolled: each managed resource carries an `instances` array with one
+ * entry per expansion. Feeding state in makes the `-3*(instances-1)` penalty
+ * accurate, so a 200-instance fan-out ranks as the boundary work it really is.
+ *
+ * This is deliberately separate and opt-in (`--state <path>`): a pure-`.tf`
+ * parse is a plain file read, while reading state pulls in a state backend's
+ * output. JSON only — no HCL, no wasm.
+ */
+
+import { readFileSync } from "fs";
+import type { TfGraph } from "./types";
+
+/** The subset of tfstate v4 the advisor reads. */
+interface TfStateResource {
+  module?: string;
+  mode?: "managed" | "data";
+  type: string;
+  name: string;
+  instances?: Array<{ attributes?: Record<string, unknown> }>;
+}
+interface TfState {
+  version?: number;
+  resources?: TfStateResource[];
+}
+
+/** A resource's resolved attributes, read from state for adoption. */
+export interface StateResource {
+  type: string;
+  name: string;
+  /** The first instance's resolved attributes (id, arn, tags, ...). */
+  attributes: Record<string, unknown>;
+}
+
+/**
+ * Read one root-module managed resource's resolved attributes from state, by
+ * Terraform address (`aws_s3_bucket.assets`). This is the true source of a
+ * Terraform-managed resource's live shape — unlike a CloudFormation export, it
+ * exists whether or not the resource was ever in a CFN stack. Returns null if
+ * the address is absent, is a data source, or is module-nested.
+ */
+export function readStateResource(statePath: string, address: string): StateResource | null {
+  const state = JSON.parse(readFileSync(statePath, "utf-8")) as TfState;
+  for (const res of state.resources ?? []) {
+    if (res.mode === "data" || res.module) continue;
+    if (`${res.type}.${res.name}` !== address) continue;
+    const attributes = res.instances?.[0]?.attributes;
+    if (!attributes) return null;
+    return { type: res.type, name: res.name, attributes };
+  }
+  return null;
+}
+
+/**
+ * Map each root-module managed resource address to its state-expanded instance
+ * count. Resources nested in a `module` are skipped: the `.tf` graph models a
+ * module as a single node, so there is no per-resource node to attach the count
+ * to (a documented v1 limitation — module internals are not descended into).
+ */
+export function readStateInstanceCounts(statePath: string): Map<string, number> {
+  const raw = readFileSync(statePath, "utf-8");
+  const state = JSON.parse(raw) as TfState;
+  const counts = new Map<string, number>();
+  for (const res of state.resources ?? []) {
+    if (res.mode === "data") continue; // data sources are not carvable nodes
+    if (res.module) continue; // nested in a module → no top-level node to map
+    const address = `${res.type}.${res.name}`;
+    counts.set(address, Array.isArray(res.instances) ? res.instances.length : 1);
+  }
+  return counts;
+}
+
+/**
+ * Overlay state instance counts onto a graph in place. Nodes absent from state
+ * keep their `.tf`-derived count of 1. Returns the same graph for chaining.
+ */
+export function applyStateCounts(graph: TfGraph, counts: Map<string, number>): TfGraph {
+  for (const node of graph.nodes) {
+    const n = counts.get(node.address);
+    if (n !== undefined) node.instances = Math.max(1, n);
+  }
+  return graph;
+}

package/src/terraform/tier-map.ts

@@ -0,0 +1,60 @@
+/**
+ * Terraform-type → native-spec tier map for the carve-out advisor (#214 T3).
+ *
+ * The AWS entries are derived from the single AWS carve-out table
+ * (`aws-resources.ts`), so the advisor ranks exactly the AWS types `carve emit`
+ * can produce — no advise↔emit cliff. Non-AWS entries (e.g. `kubernetes_manifest`)
+ * are listed here directly; emit for those is a separate target.
+ *
+ *   tier 1 — a clean 1:1 native resource
+ *   tier 2 — maps, but with reshaping
+ *   tier 3 — a hard/partial map
+ *   null   — no known native mapping (unsupported provider/type) → score 0
+ */
+
+import { AWS_CARVE_TYPES } from "./aws-resources";
+
+export interface TierInfo {
+  tier: 1 | 2 | 3;
+  /** The native spec type a carve would target, for the report. */
+  mapsTo: string;
+}
+
+/** TF resource type → native tier. Absent = unsupported (score 0). */
+export const TIER_MAP: Record<string, TierInfo> = {
+  // AWS: derived from the carve-out table so advise and emit stay in lockstep.
+  ...Object.fromEntries(AWS_CARVE_TYPES.map((t) => [t.tfType, { tier: t.tier, mapsTo: t.nativeType }])),
+  // Kubernetes — near-1:1 manifest. Ranked by advise; emit support is a separate target.
+  kubernetes_manifest: { tier: 1, mapsTo: "k8s:manifest" },
+};
+
+/**
+ * TF "sub-resource" types that inline into a parent resource rather than
+ * standing alone (TF splits config the native spec keeps in one resource).
+ * A sub-resource that shares its parent's name is folded into the parent's
+ * carve set: it is not ranked on its own, and its edge to the parent does not
+ * count as inbound boundary work — inlining it is free.
+ *
+ * Maps sub-resource TF type → parent TF type.
+ */
+export const FOLDS_INTO: Record<string, string> = {
+  aws_s3_bucket_versioning: "aws_s3_bucket",
+  aws_s3_bucket_acl: "aws_s3_bucket",
+  aws_s3_bucket_policy: "aws_s3_bucket",
+  aws_s3_bucket_public_access_block: "aws_s3_bucket",
+  aws_s3_bucket_server_side_encryption_configuration: "aws_s3_bucket",
+  aws_s3_bucket_lifecycle_configuration: "aws_s3_bucket",
+};
+
+/**
+ * The HCL attribute carrying a resource's physical name, per type — derived
+ * from the AWS carve-out table. Used for the graph's identity and the
+ * live-import hint. Absent → fall back to the TF logical name.
+ */
+export const IDENTITY_ATTR: Record<string, string> = Object.fromEntries(
+  AWS_CARVE_TYPES.filter((t) => t.identityAttr).map((t) => [t.tfType, t.identityAttr!]),
+);
+
+export function resolveTier(tfType: string): TierInfo | null {
+  return TIER_MAP[tfType] ?? null;
+}

package/src/terraform/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Types for the read-only Terraform carve-out advisor (#214).
+ *
+ * The advisor never emits, patches, or mutates state. It parses a Terraform
+ * estate into a dependency graph and scores each resource/module by
+ * "peelability" — how cleanly it could later be carved into native chant
+ * source (the emit/boundary/apply phases stay in #197, gated on demand).
+ *
+ * The graph layer here is intentionally pure: it consumes the JSON shape
+ * `@cdktf/hcl2json` produces (see `parse.ts`), so the graph and scoring can
+ * be tested without loading the wasm parser.
+ */
+
+/** A node in the Terraform dependency graph — one resource or module block. */
+export interface TfNode {
+  /** Terraform address, e.g. `aws_s3_bucket.assets` or `module.cdn`. */
+  address: string;
+  kind: "resource" | "module";
+  /** Resource type (`aws_s3_bucket`); undefined for modules. */
+  type?: string;
+  /** Local name (`assets`) or module name (`cdn`). */
+  name: string;
+  /**
+   * State-expanded instance count. 1 unless `count`/`for_each` is present and
+   * a `.tfstate` was read (see `state.ts`, #214 T2). Without state, a block
+   * with `count`/`for_each` reports 1 and sets `hasDynamic`.
+   */
+  instances: number;
+  /** `count`, `for_each`, a `data` source, or an unresolved interpolation is present. */
+  hasDynamic: boolean;
+  /**
+   * The resource's physical name, when it is a plain literal in the HCL (e.g.
+   * `bucket = "myapp-assets-prod"`). Used to build the live-import selector on
+   * emit. Undefined when the identity attribute is absent or interpolated.
+   */
+  identity?: string;
+}
+
+/**
+ * A directed dependency edge: `from` references `to`.
+ *
+ * For a candidate carve target T:
+ *  - inbound  = edges where `to === T`  (surviving resources depend on T → each is a data-source patch)
+ *  - outbound = edges where `from === T` (T depends on survivors → a deferred deploy-time input)
+ */
+export interface TfEdge {
+  from: string;
+  to: string;
+  /** The attribute path(s) referenced, e.g. `["id", "arn"]`. */
+  attrs: string[];
+}
+
+export interface TfGraph {
+  nodes: TfNode[];
+  edges: TfEdge[];
+}
+
+/**
+ * The subset of `@cdktf/hcl2json`'s `parse()` output the advisor reads. A
+ * merged tree across every `.tf` file in the estate. Values are left as the
+ * raw hcl2json encoding (interpolations survive as `"${...}"` strings), which
+ * is what edge extraction scans.
+ */
+export interface Hcl2JsonTree {
+  resource?: Record<string, Record<string, unknown[]>>;
+  module?: Record<string, unknown[]>;
+  data?: Record<string, Record<string, unknown[]>>;
+  [k: string]: unknown;
+}