@intentius/chant 0.18.36 → 0.19.0

package/src/cli/commands/carve-emit-state.test.ts

@@ -0,0 +1,114 @@
+import { describe, test, expect, vi } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveEmit, formatCarveEmit } from "./carve-emit";
+import { loadHcl2json } from "../../terraform/parse";
+import type { ImportResult, LiveImportOptions } from "./import";
+import type { LexiconPlugin } from "../../lexicon";
+
+/**
+ * Real (non-faked) adoption from `.tfstate` — #1009. A Terraform-managed
+ * resource is not in any CloudFormation stack, so the live (CFN) import path
+ * cannot adopt it; its resolved shape lives in the state file. This exercises
+ * the offline state-adoption path end to end with real state data. Skips only
+ * if the wasm parser (for the boundary report) is absent.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `
+resource "aws_s3_bucket" "assets" { bucket = "myapp-assets-prod" }
+resource "aws_lambda_function" "api" {
+  environment { variables = { B = aws_s3_bucket.assets.bucket } }
+}
+`;
+
+// A realistic terraform.tfstate v4 with the bucket's resolved attributes.
+const TFSTATE = JSON.stringify({
+  version: 4,
+  terraform_version: "1.7.0",
+  resources: [
+    {
+      mode: "managed",
+      type: "aws_s3_bucket",
+      name: "assets",
+      provider: 'provider["registry.terraform.io/hashicorp/aws"]',
+      instances: [
+        {
+          attributes: {
+            id: "myapp-assets-prod",
+            bucket: "myapp-assets-prod",
+            arn: "arn:aws:s3:::myapp-assets-prod",
+            tags: { Team: "web", Env: "prod" },
+            force_destroy: false,
+          },
+        },
+      ],
+    },
+  ],
+});
+
+// The live-import fake must never be called on the state path.
+const liveImport = vi.fn(
+  async (_p: LexiconPlugin[], _o: LiveImportOptions): Promise<ImportResult> => ({
+    success: true,
+    generatedFiles: [],
+    warnings: [],
+  }),
+);
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-emit-state-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), ESTATE);
+    writeFileSync(join(dir, "terraform.tfstate"), TFSTATE);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carve emit --state (real adoption from tfstate)", () => {
+  test("emits native chant source from real state attributes, no cloud call", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const out = join(dir, "carveout");
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", statePath: join(dir, "terraform.tfstate"), output: out },
+        { plugins: [], liveImport },
+      );
+
+      expect(res.ok).toBe(true);
+      expect(res.source).toBe("tfstate");
+      expect(liveImport).not.toHaveBeenCalled(); // offline — no cloud
+
+      // A real .ts file with the native constructor + props from real state.
+      expect(res.emittedFiles).toEqual([join(out, "assets.ts")]);
+      const emitted = readFileSync(res.emittedFiles![0], "utf-8");
+      expect(emitted).toContain("new Bucket({");
+      expect(emitted).toContain('BucketName: "myapp-assets-prod"');
+      expect(emitted).toContain("Adopted from Terraform state");
+
+      // Boundary still classified (the Lambda inbound).
+      expect(res.report!.inbound.map((e) => e.survivor)).toEqual(["aws_lambda_function.api"]);
+
+      const text = formatCarveEmit(res);
+      expect(text).toContain("Adopted from Terraform state (offline)");
+    });
+  });
+
+  test("without --state or --env it explains both adoption sources", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveEmit({ from: dir, select: "aws_s3_bucket.assets" }, { plugins: [], liveImport });
+      expect(res.ok).toBe(false);
+      expect(res.error).toMatch(/--state .*or --env/);
+    });
+  });
+});

package/src/cli/commands/carve-emit.test.ts

@@ -0,0 +1,158 @@
+import { describe, test, expect, vi } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveEmit, formatCarveEmit } from "./carve-emit";
+import { loadHcl2json } from "../../terraform/parse";
+import type { ImportResult, LiveImportOptions } from "./import";
+import type { LexiconPlugin } from "../../lexicon";
+
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `
+resource "aws_s3_bucket" "assets" {
+  bucket = "myapp-assets-prod"
+}
+resource "aws_s3_bucket_versioning" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  versioning_configuration { status = "Enabled" }
+}
+resource "aws_lambda_function" "api" {
+  function_name = "myapp-api"
+  environment {
+    variables = {
+      ASSETS_BUCKET = aws_s3_bucket.assets.bucket
+      ASSETS_ARN    = aws_s3_bucket.assets.arn
+    }
+  }
+}
+resource "random_pet" "suffix" {
+  length = 2
+}
+`;
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-carve-emit-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), ESTATE);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const fakeImport = (files: string[] = ["infra/assets.ts"]) =>
+  vi.fn(
+    async (_plugins: LexiconPlugin[], _options: LiveImportOptions): Promise<ImportResult> => ({
+      success: true,
+      generatedFiles: files,
+      warnings: [],
+      lexicon: "aws",
+    }),
+  );
+
+const noPlugins: LexiconPlugin[] = [];
+
+describe("carveEmit — validation", () => {
+  test("requires --from, --select, --env", async () => {
+    const li = fakeImport();
+    expect((await carveEmit({}, { plugins: noPlugins, liveImport: li })).error).toContain("--from");
+    expect((await carveEmit({ from: "/x" }, { plugins: noPlugins, liveImport: li })).error).toContain("--select");
+    expect(li).not.toHaveBeenCalled();
+  });
+});
+
+describe("carveEmit — emit + boundary", () => {
+  test("adopts the selected resource with a native selector and reports the boundary", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const li = fakeImport(["infra/assets.ts"]);
+      const reportFile = join(dir, "carveout-report.json");
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", env: "prod", reportFile },
+        { plugins: noPlugins, liveImport: li },
+      );
+
+      expect(res.ok).toBe(true);
+      // Live selector is by native type: the CFN import filters by logical id,
+      // which is not the Terraform physical name, so name is not passed here.
+      expect(res.selector).toEqual({ type: "AWS::S3::Bucket" });
+      expect(li).toHaveBeenCalledOnce();
+      expect(li.mock.calls[0][1]).toMatchObject({
+        environment: "prod",
+        selector: { type: "AWS::S3::Bucket" },
+      });
+
+      // Boundary: one inbound edge from the Lambda; versioning folded away.
+      expect(res.report!.inbound).toHaveLength(1);
+      expect(res.report!.inbound[0].survivor).toBe("aws_lambda_function.api");
+      expect(res.report!.outbound).toHaveLength(0);
+
+      // Report written to disk.
+      const written = JSON.parse(readFileSync(reportFile, "utf-8"));
+      expect(written.target).toBe("aws_s3_bucket.assets");
+      expect(written.reversible).toBe(true);
+    });
+  });
+
+  test("refuses to emit an unsupported type (no native mapping)", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const li = fakeImport();
+      const res = await carveEmit(
+        { from: dir, select: "random_pet.suffix", env: "prod" },
+        { plugins: noPlugins, liveImport: li },
+      );
+      expect(res.ok).toBe(false);
+      expect(res.error).toMatch(/no known native mapping/i);
+      expect(li).not.toHaveBeenCalled(); // never adopts something it can't map
+    });
+  });
+
+  test("errors when the address is not in the estate", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.nope", env: "prod" },
+        { plugins: noPlugins, liveImport: fakeImport() },
+      );
+      expect(res.ok).toBe(false);
+      expect(res.error).toContain("not found");
+    });
+  });
+
+  test("formatCarveEmit describes the adoption and the pending boundary work", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", env: "prod" },
+        { plugins: noPlugins, liveImport: fakeImport(["infra/assets.ts"]) },
+      );
+      const text = formatCarveEmit(res);
+      expect(text).toContain("observe position, reversible");
+      expect(text).toContain("Adopted live as AWS::S3::Bucket");
+      expect(text).toContain("inbound");
+      expect(text).toContain("carve bridge"); // points at the next step
+    });
+  });
+
+  test("--live-name narrows the live selector to a CFN logical id", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const li = fakeImport(["infra/assets.ts"]);
+      const res = await carveEmit(
+        { from: dir, select: "aws_s3_bucket.assets", env: "prod", liveName: "AssetsBucket" },
+        { plugins: noPlugins, liveImport: li },
+      );
+      expect(res.ok).toBe(true);
+      expect(res.selector).toEqual({ type: "AWS::S3::Bucket", name: "AssetsBucket" });
+      expect(formatCarveEmit(res)).toContain('logical id "AssetsBucket"');
+    });
+  });
+});

package/src/cli/commands/carve-emit.ts

@@ -0,0 +1,181 @@
+/**
+ * `chant carve emit` — the first strangler-fig emit step (#197).
+ *
+ * Given a resource selected from a Terraform estate, it:
+ *  1. classifies the boundary (which edges the carve cuts),
+ *  2. adopts the live resource into typed chant source via live import
+ *     (`chant import --from <env>` machinery — cloud→code, read-only export),
+ *  3. writes a boundary report.
+ *
+ * It does not patch the surviving Terraform or apply anything — that is the
+ * boundary-bridging and apply-graduation work (later PRs). This lands the
+ * resource at the observe position: emitted, reversible, nothing mutated.
+ */
+
+import { existsSync, statSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
+import { boundaryReport, type CarveReport } from "../../terraform/carve";
+import { resolveTier } from "../../terraform/tier-map";
+import { readStateResource } from "../../terraform/state";
+import { adoptFromState, canAdoptFromState, supportedStateAdoptionTypes } from "../../terraform/adopt-state";
+import type { LexiconPlugin, ResourceSelector } from "../../lexicon";
+import type { ImportResult, LiveImportOptions } from "./import";
+
+export interface CarveEmitOptions {
+  /** Terraform estate directory (`--from`). */
+  from?: string;
+  /** Terraform address to carve, e.g. `aws_s3_bucket.assets` (`--select`). */
+  select?: string;
+  /** Live environment to adopt from (`--env`). */
+  env?: string;
+  /**
+   * CloudFormation logical ID to adopt on the live path (`--live-name`). The
+   * live import filters a stack's template by logical ID, which is not the
+   * Terraform physical name — so the live selector is by native type by
+   * default, and this narrows it when a stack has several of that type.
+   */
+  liveName?: string;
+  /** Opt-in `.tfstate` for instance counts (`--state`). */
+  statePath?: string;
+  /** Output directory for the emitted source (`--output`). */
+  output?: string;
+  /** Write the boundary report JSON here (`--report`). */
+  reportFile?: string;
+}
+
+/** Injected so tests exercise emit without cloud calls. */
+export interface CarveEmitDeps {
+  plugins: LexiconPlugin[];
+  liveImport: (plugins: LexiconPlugin[], options: LiveImportOptions) => Promise<ImportResult>;
+}
+
+export interface CarveEmitResult {
+  ok: boolean;
+  error?: string;
+  report?: CarveReport;
+  emit?: ImportResult;
+  /** The selector used for the live adoption, for transparency (cloud path). */
+  selector?: ResourceSelector;
+  /** How the resource was adopted. */
+  source?: "tfstate" | "live";
+  /** Emitted file path(s). */
+  emittedFiles?: string[];
+}
+
+export async function carveEmit(opts: CarveEmitOptions, deps: CarveEmitDeps): Promise<CarveEmitResult> {
+  if (!opts.from) return { ok: false, error: "chant carve emit requires --from <terraform-dir>" };
+  if (!opts.select) return { ok: false, error: "chant carve emit requires --select <tf-address>" };
+  // Adoption source: --state adopts offline from tfstate (correct for a
+  // Terraform-managed resource); --env adopts via the live cloud import path.
+  if (!opts.statePath && !opts.env) {
+    return { ok: false, error: "chant carve emit requires --state <tfstate> (offline, recommended) or --env <environment>" };
+  }
+  if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${opts.from}` };
+  }
+
+  let report: CarveReport | null;
+  let tfType: string | undefined;
+  try {
+    const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
+    report = boundaryReport(graph, opts.select);
+    tfType = graph.nodes.find((n) => n.address === opts.select)?.type;
+  } catch (err) {
+    if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
+    return { ok: false, error: `Failed to parse Terraform in ${opts.from}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (!report) return { ok: false, error: `${opts.select} not found in ${opts.from}` };
+
+  const tier = tfType ? resolveTier(tfType) : null;
+  if (!tier) {
+    return {
+      ok: false,
+      error: `${opts.select} (${tfType ?? "unknown type"}) has no known native mapping, so it cannot be emitted. Advisor bands it "leave in Terraform".`,
+    };
+  }
+
+  if (opts.reportFile) writeFileSync(opts.reportFile, JSON.stringify(report, null, 2));
+
+  // ── Adoption path 1: from .tfstate (offline, correct for TF-managed) ──
+  if (opts.statePath) {
+    if (!canAdoptFromState(tfType!)) {
+      return {
+        ok: false,
+        error:
+          `${tfType} cannot be adopted from state yet (no native constructor mapping).\n` +
+          `Supported types: ${supportedStateAdoptionTypes().join(", ")}. ` +
+          `Coverage is expanding — see chant issue #1001.`,
+      };
+    }
+    const stateResource = readStateResource(opts.statePath, opts.select);
+    if (!stateResource) {
+      return { ok: false, error: `${opts.select} not found in state ${opts.statePath} (or is a data source / module-nested).` };
+    }
+    const adopted = adoptFromState(stateResource);
+    if (!adopted) return { ok: false, error: `Could not adopt ${opts.select} from state.` };
+
+    const outDir = opts.output ?? join(opts.from, "carveout");
+    mkdirSync(outDir, { recursive: true });
+    const outPath = join(outDir, adopted.fileName);
+    writeFileSync(outPath, adopted.content);
+
+    return { ok: true, report, source: "tfstate", emittedFiles: [outPath] };
+  }
+
+  // ── Adoption path 2: live import (cloud→code) ──
+  // The live import filters a CloudFormation stack's template by logical ID, not
+  // the Terraform physical name — so select by native type, narrowing to a
+  // logical ID only when the caller passes --live-name (a stack with several of
+  // that type). `identity` (the TF physical name) is not a valid CFN selector.
+  const selector: ResourceSelector = opts.liveName
+    ? { type: tier.mapsTo, name: opts.liveName }
+    : { type: tier.mapsTo };
+
+  const emit = await deps.liveImport(deps.plugins, {
+    environment: opts.env!,
+    selector,
+    output: opts.output,
+    lexicon: tier.mapsTo.split("::")[0]?.toLowerCase() === "aws" ? "aws" : undefined,
+  });
+
+  return { ok: true, report, emit, selector, source: "live", emittedFiles: emit.generatedFiles };
+}
+
+/** Human-readable emit summary: what was adopted and what boundary work remains. */
+export function formatCarveEmit(result: CarveEmitResult): string {
+  if (!result.ok || !result.report) return result.error ?? "carve emit failed";
+  const r = result.report;
+  const lines: string[] = [];
+  lines.push(`Carved ${r.target} (peelability ${r.peelability}) — observe position, reversible.`);
+  if (result.source === "tfstate") {
+    lines.push("  Adopted from Terraform state (offline).");
+  } else if (result.selector) {
+    const named = result.selector.name ? ` (logical id "${result.selector.name}")` : "";
+    lines.push(`  Adopted live as ${result.selector.type}${named}.`);
+  }
+  if (result.emittedFiles?.length) {
+    lines.push(`  Emitted: ${result.emittedFiles.join(", ")}`);
+  }
+  if (r.carveSet.length > 1) {
+    const folded = r.carveSet.filter((m) => m.foldedInto).map((m) => m.address);
+    lines.push(`  Folded in: ${folded.join(", ")}`);
+  }
+  lines.push("");
+  lines.push("Boundary (not yet patched — that is `carve bridge`, the next step):");
+  if (r.inbound.length === 0 && r.outbound.length === 0) {
+    lines.push("  none — a clean leaf, nothing depends on it and it depends on nothing.");
+  }
+  for (const e of r.inbound) {
+    lines.push(`  inbound   ${e.survivor} reads ${e.attrs.join(", ")} → rewrite to a data source (required immediately)`);
+  }
+  for (const e of r.outbound) {
+    lines.push(`  outbound  ${e.carved} reads ${e.survivor}.${e.attrs.join(", ")} → deferred deploy-time input (at apply)`);
+  }
+  if (r.diagnostics.length) {
+    lines.push("");
+    for (const d of r.diagnostics) lines.push(`  ! ${d}`);
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/carve.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { carveAdvise, carveJson, formatCarveReport } from "./carve";
+import { loadHcl2json } from "../../terraform/parse";
+
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = `
+resource "aws_s3_bucket" "assets" {
+  bucket = "myapp-assets-prod"
+}
+resource "aws_s3_bucket_versioning" "assets" {
+  bucket = aws_s3_bucket.assets.id
+  versioning_configuration { status = "Enabled" }
+}
+resource "aws_lambda_function" "api" {
+  environment {
+    variables = {
+      ASSETS_BUCKET = aws_s3_bucket.assets.bucket
+    }
+  }
+}
+resource "random_pet" "name" {
+  length = 2
+}
+`;
+
+async function withEstate<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-carve-"));
+  try {
+    writeFileSync(join(dir, "main.tf"), ESTATE);
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe("carveAdvise", () => {
+  test("requires --from", async () => {
+    const r = await carveAdvise({});
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("--from");
+  });
+
+  test("errors on a non-directory", async () => {
+    const r = await carveAdvise({ from: join(tmpdir(), "definitely-not-here-xyz") });
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("Not a directory");
+  });
+
+  test("scores a real estate, ranks it, and writes a report (real wasm)", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const reportFile = join(dir, "report.json");
+      const r = await carveAdvise({ from: dir, reportFile });
+      expect(r.ok).toBe(true);
+
+      const addrs = (r.results ?? []).map((x) => x.address);
+      // versioning is folded into the bucket, so it is not ranked on its own.
+      expect(addrs).not.toContain("aws_s3_bucket_versioning.assets");
+      expect(addrs).toContain("aws_s3_bucket.assets");
+      expect(addrs).toContain("random_pet.name");
+
+      const bucket = r.results!.find((x) => x.address === "aws_s3_bucket.assets")!;
+      expect(bucket.score).toBe(88);
+      expect(bucket.band).toBe("clean leaf");
+
+      const petunia = r.results!.find((x) => x.address === "random_pet.name")!;
+      expect(petunia.score).toBe(0); // unsupported provider
+
+      // report file is valid JSON with the advisory banner + band counts
+      const payload = JSON.parse(readFileSync(reportFile, "utf-8"));
+      expect(payload.advisory).toContain("read-only");
+      expect(payload.bands["clean leaf"]).toBeGreaterThanOrEqual(1);
+      expect(payload.count).toBe(r.results!.length);
+    });
+  });
+
+  test("formatCarveReport groups by band and never suggests a mutation", async () => {
+    if (!parserAvailable) return;
+    await withEstate(async (dir) => {
+      const r = await carveAdvise({ from: dir });
+      const text = formatCarveReport(r);
+      expect(text).toContain("CLEAN LEAF");
+      expect(text).toContain("LEAVE IN TERRAFORM");
+      expect(text).toContain("Advises only");
+      expect(text).not.toMatch(/terraform state rm|apply|destroy/i);
+    });
+  });
+
+  test("carveJson carries the read-only advisory banner", () => {
+    const payload = carveJson({ ok: true, from: "x", results: [] }) as { advisory: string; count: number };
+    expect(payload.advisory).toContain("read-only");
+    expect(payload.count).toBe(0);
+  });
+});

package/src/cli/commands/carve.ts

@@ -0,0 +1,123 @@
+/**
+ * `chant carve advise` — the read-only Terraform peelability advisor (#214).
+ *
+ * Points at a Terraform estate and reports which resources/modules are cheap to
+ * carve into native chant later and which should stay in Terraform. It emits
+ * nothing, patches nothing, and touches no live resource — pure analysis. The
+ * emit/boundary/apply phases stay in #197, gated on demand.
+ */
+
+import { existsSync, statSync, writeFileSync } from "fs";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse";
+import { scoreEstate, type Peelability, type PeelabilityBand } from "../../terraform/score";
+
+export interface CarveAdviseOptions {
+  /** Terraform estate directory (from `--from`). */
+  from?: string;
+  /** Opt-in `.tfstate` path (from `--state`): accurate fan-out instance counts. */
+  statePath?: string;
+  /** Write the full JSON report to this path (from `--report <path>`). */
+  reportFile?: string;
+}
+
+export interface CarveAdviseResult {
+  ok: boolean;
+  error?: string;
+  from?: string;
+  results?: Peelability[];
+}
+
+const BAND_ORDER: PeelabilityBand[] = ["clean leaf", "carvable w/ edits", "leave in Terraform"];
+
+export async function carveAdvise(opts: CarveAdviseOptions): Promise<CarveAdviseResult> {
+  if (!opts.from) {
+    return { ok: false, error: "chant carve advise requires --from <terraform-dir>" };
+  }
+  if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${opts.from}` };
+  }
+  if (opts.statePath && !existsSync(opts.statePath)) {
+    return { ok: false, error: `State file not found: ${opts.statePath}` };
+  }
+
+  let results: Peelability[];
+  try {
+    results = scoreEstate(await parseTerraformDir(opts.from, { statePath: opts.statePath }));
+  } catch (err) {
+    if (err instanceof Hcl2JsonNotInstalled) return { ok: false, error: err.message };
+    return { ok: false, error: `Failed to parse Terraform in ${opts.from}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (opts.reportFile) {
+    writeFileSync(opts.reportFile, JSON.stringify(carveJson({ ok: true, from: opts.from, results }), null, 2));
+  }
+
+  return { ok: true, from: opts.from, results };
+}
+
+/** The `--json` / `--report` payload. */
+export function carveJson(result: CarveAdviseResult): unknown {
+  const results = result.results ?? [];
+  const counts = Object.fromEntries(
+    BAND_ORDER.map((b) => [b, results.filter((r) => r.band === b).length]),
+  );
+  return {
+    from: result.from,
+    advisory: "read-only — emits nothing, patches nothing, touches no live resource",
+    count: results.length,
+    bands: counts,
+    resources: results,
+  };
+}
+
+/** Human-readable banded, ranked summary. */
+export function formatCarveReport(result: CarveAdviseResult): string {
+  const results = result.results ?? [];
+  if (results.length === 0) {
+    return `No carvable resources found in ${result.from}\n(only data sources, providers, or unsupported types were present).`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`Terraform carve-out advisory for ${result.from}`);
+  lines.push(`  ${results.length} resource(s)/module(s) scored. Advises only — nothing is emitted or changed.`);
+  lines.push("");
+
+  for (const band of BAND_ORDER) {
+    const inBand = results.filter((r) => r.band === band);
+    if (inBand.length === 0) continue;
+    lines.push(`${bandLabel(band)}  (${inBand.length})`);
+    for (const r of inBand) {
+      const target = r.mapsTo ? ` -> ${r.mapsTo}` : "";
+      lines.push(`  ${String(r.score).padStart(3)}  ${r.address}${target}`);
+      lines.push(`       ${reasons(r)}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("Bands: 80-100 carve now | 50-79 carve with boundary edits | 0-49 leave in Terraform");
+  return lines.join("\n").trimEnd();
+}
+
+function bandLabel(band: PeelabilityBand): string {
+  switch (band) {
+    case "clean leaf":
+      return "CLEAN LEAF — carve now";
+    case "carvable w/ edits":
+      return "CARVABLE — has boundary work";
+    case "leave in Terraform":
+      return "LEAVE IN TERRAFORM";
+  }
+}
+
+/** One-line explanation of what drove a score, from its breakdown. */
+function reasons(r: Peelability): string {
+  const b = r.breakdown;
+  if (b.tier === null) return "no known native mapping (unsupported provider/type)";
+  const parts: string[] = [];
+  if (b.inbound) parts.push(`${b.inbound} inbound (data-source patch each)`);
+  if (b.outbound) parts.push(`${b.outbound} outbound (deferred input each)`);
+  if (b.tier > 1) parts.push(`tier ${b.tier} map`);
+  if (b.hasDynamic) parts.push("count/for_each/data present");
+  if (b.instances > 1) parts.push(`${b.instances} instances`);
+  return parts.length ? parts.join(", ") : "clean 1:1 native map, no boundary edges";
+}