@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/commands/carve-emit.js

@@ -0,0 +1,332 @@
+/**
+ * `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 { basename, join, resolve } from "path";
+import { cdkNotSupported, isCloudAssembly } from "../../cdk/assembly.js";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse.js";
+import { boundaryReport, deferredParamName } from "../../terraform/carve.js";
+import { carveEmitTypes, resolveTier } from "../../terraform/tier-map.js";
+import { resolveEmitProvider } from "../../terraform/carve-provider.js";
+import { readStateResource } from "../../terraform/state.js";
+import { writeCarveManifest } from "../../terraform/manifest.js";
+import { adoptFromState } from "../../terraform/adopt-state.js";
+import { generateTsConfig, getChantVersion, SCAFFOLD_DEV_DEPENDENCIES } from "./init.js";
+export async function carveEmit(opts, deps) {
+    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}` };
+    }
+    if (isCloudAssembly(opts.from))
+        return { ok: false, error: cdkNotSupported(opts.from, "emit") };
+    let report;
+    let tfType;
+    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}` };
+    if (!tfType || !resolveTier(tfType)) {
+        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".`,
+        };
+    }
+    // `carve advise` ranks every type a provider declares; emit produces source
+    // only for the ones that provider can adopt. Both adoption paths refuse the
+    // rest here — before any file is written or any cloud call is made — so
+    // neither path can proceed on a type the other rejects.
+    const provider = resolveEmitProvider(tfType);
+    if (!provider) {
+        return {
+            ok: false,
+            error: `${tfType} cannot be emitted yet (no carve provider adopts it).\n` +
+                `Supported types: ${carveEmitTypes().join(", ")}. ` +
+                `Coverage is expanding — see chant issue #1001.`,
+        };
+    }
+    if (opts.reportFile)
+        writeFileSync(opts.reportFile, JSON.stringify(report, null, 2));
+    // ── Adoption path 1: from .tfstate (offline, correct for TF-managed) ──
+    if (opts.statePath) {
+        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).` };
+        }
+        // Deferred outbound inputs → real build parameters (#998): each survivor
+        // value the carved block read enters the emitted project as a declared
+        // param, defaulted to the value the state resolved.
+        const params = deferredParams(report, stateResource.attributes);
+        // The carve set's folded sub-resources come out of the same state file:
+        // their mappable attributes belong in the parent's emitted props (#1637).
+        const folded = report.carveSet
+            .filter((m) => m.foldedInto)
+            .map((m) => readStateResource(opts.statePath, m.address))
+            .filter((r) => r !== null);
+        const adopted = adoptFromState(stateResource, params, folded);
+        if (!adopted)
+            return { ok: false, error: `Could not adopt ${opts.select} from state.` };
+        // The output dir is a buildable chant project: source in src/, plus the
+        // config + package.json scaffold (written once, never overwritten).
+        const outDir = opts.output ?? join(opts.from, "carveout");
+        const srcDir = join(outDir, "src");
+        mkdirSync(srcDir, { recursive: true });
+        const outPath = join(srcDir, adopted.fileName);
+        writeFileSync(outPath, adopted.content);
+        const scaffolded = scaffoldProject(outDir, provider.lexicon, params);
+        const manifestPath = persistManifest(outDir, opts, report, tfType, "tfstate", [outPath], params);
+        return {
+            ok: true,
+            report,
+            source: "tfstate",
+            emittedFiles: [outPath],
+            scaffolded,
+            manifestPath,
+            params,
+            folded: adopted.folded,
+        };
+    }
+    // ── Adoption path 2: live import (cloud→code) ──
+    // The provider names the selector type its live export filters on — for aws a
+    // CloudFormation type, filtered by logical ID rather than the Terraform
+    // physical name, so `--live-name` (not `identity`) is what narrows a stack
+    // holding several of that type.
+    const selectorType = provider.liveSelectorType?.(tfType);
+    if (!selectorType) {
+        return {
+            ok: false,
+            error: `${tfType} has no live adoption path — the ${provider.name} carve provider adopts it from state only.\n` +
+                `Re-run with --state <tfstate>.`,
+        };
+    }
+    const selector = opts.liveName
+        ? { type: selectorType, name: opts.liveName }
+        : { type: selectorType };
+    const emit = await deps.liveImport(deps.plugins, {
+        environment: opts.env,
+        selector,
+        output: opts.output,
+        lexicon: provider.lexicon,
+    });
+    // A failed import emitted no source. Reporting success here would write a
+    // carve manifest that `carve bridge` composes from, and bridge excises the
+    // survivor's `.tf` block for the resource — so the estate would lose a
+    // declaration that was never adopted. Fail, and persist nothing.
+    if (!emit.success) {
+        return {
+            ok: false,
+            error: `Live import of ${selector.type} from ${opts.env} failed: ${emit.error ?? "no error reported"}\n` +
+                `Nothing was emitted and no carve manifest was written.`,
+            report,
+            emit,
+            selector,
+            source: "live",
+        };
+    }
+    const outDir = opts.output ?? join(opts.from, "carveout");
+    const manifestPath = persistManifest(outDir, opts, report, tfType, "live", emit.generatedFiles ?? []);
+    return { ok: true, report, emit, selector, source: "live", emittedFiles: emit.generatedFiles, manifestPath };
+}
+/**
+ * Turn the boundary report's outbound edges into build parameters (#998): one
+ * per carved-block attribute that read a survivor (`via`), named after that
+ * attribute, defaulted to the value the state resolved for it. A non-scalar
+ * value (a nested block) is declared without a default (`required: false`) —
+ * it documents the deferred input without blocking an out-of-the-box build.
+ */
+function deferredParams(report, attributes) {
+    const byName = new Map();
+    for (const edge of report.outbound) {
+        for (const tfAttr of edge.via ?? []) {
+            const name = deferredParamName(tfAttr);
+            const raw = attributes[tfAttr];
+            const scalar = typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean" ? raw : undefined;
+            const prev = byName.get(name);
+            byName.set(name, {
+                name,
+                tfAttr,
+                survivor: prev && prev.survivor !== edge.survivor ? `${prev.survivor}, ${edge.survivor}` : edge.survivor,
+                attrs: [...new Set([...(prev?.attrs ?? []), ...edge.attrs])].sort(),
+                default: scalar,
+            });
+        }
+    }
+    return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * Scaffold the emitted source into a buildable chant project: chant.config.ts,
+ * package.json, tsconfig.json, with the tsconfig and devDependencies `chant init`
+ * writes (#3233), so `npm install && npm run build` works in the output dir as-is. Existing files
+ * are never overwritten (re-emits and user edits survive). Deferred inputs are
+ * declared as `buildParams` (#998), defaults taken from the state's resolved
+ * values, so the first build reproduces what is live while every survivor-fed
+ * value stays overridable (`--param <name>=<value>`).
+ */
+function scaffoldProject(outDir, lexicon, params = []) {
+    const ver = getChantVersion();
+    const packageJson = {
+        name: "chant-carveout",
+        version: "0.1.0",
+        type: "module",
+        scripts: {
+            build: `chant build src --lexicon ${lexicon}`,
+            lint: "chant lint src",
+        },
+        dependencies: {
+            "@intentius/chant": `^${ver}`,
+            [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}`,
+        },
+        devDependencies: { ...SCAFFOLD_DEV_DEPENDENCIES },
+    };
+    const files = [
+        ["package.json", JSON.stringify(packageJson, null, 2) + "\n"],
+        ["chant.config.ts", renderConfig(lexicon, params)],
+        ["tsconfig.json", generateTsConfig() + "\n"],
+    ];
+    const written = [];
+    for (const [name, content] of files) {
+        const path = join(outDir, name);
+        if (existsSync(path))
+            continue;
+        writeFileSync(path, content);
+        written.push(path);
+    }
+    return written;
+}
+/** Render the scaffolded `chant.config.ts`, declaring deferred inputs as `buildParams` (#998). */
+function renderConfig(lexicon, params) {
+    const L = [];
+    L.push(`import type { ChantConfig } from "@intentius/chant";`);
+    L.push("");
+    L.push("export default {");
+    L.push(`  lexicons: ["${lexicon}"],`);
+    if (params.length) {
+        L.push("  // Deferred deploy-time inputs — values the Terraform source read from");
+        L.push("  // surviving resources. Defaults are the values the tfstate resolved;");
+        L.push("  // override per build with --param <name>=<value>.");
+        L.push("  buildParams: {");
+        for (const p of params) {
+            const type = typeof p.default === "number" ? "number" : typeof p.default === "boolean" ? "boolean" : "string";
+            L.push(`    ${p.name}: {`);
+            L.push(`      type: ${JSON.stringify(type)},`);
+            if (p.default !== undefined) {
+                L.push(`      default: ${JSON.stringify(p.default)},`);
+            }
+            else {
+                L.push(`      required: false,`);
+            }
+            L.push(`      description: ${JSON.stringify(`was ${p.survivor}.${p.attrs.join("/")} in Terraform (deferred deploy-time input)`)},`);
+            L.push("    },");
+        }
+        L.push("  },");
+    }
+    L.push("} satisfies ChantConfig;");
+    return L.join("\n") + "\n";
+}
+/** Persist the carve state manifest so bridge/apply compose with this emit. */
+function persistManifest(outDir, opts, report, tfType, source, files, params = []) {
+    const manifest = {
+        version: 1,
+        target: report.target,
+        tfType,
+        from: resolve(opts.from),
+        statePath: opts.statePath ? resolve(opts.statePath) : undefined,
+        boundary: report,
+        emit: {
+            source,
+            files: files.map((f) => resolve(f)),
+            params: params.length
+                ? Object.fromEntries(params.map((p) => [p.name, { tfAttr: p.tfAttr, survivor: p.survivor, attrs: p.attrs, default: p.default }]))
+                : undefined,
+            at: new Date().toISOString(),
+        },
+    };
+    return writeCarveManifest(outDir, manifest);
+}
+/** Human-readable emit summary: what was adopted and what boundary work remains. */
+export function formatCarveEmit(result) {
+    if (!result.ok || !result.report)
+        return result.error ?? "carve emit failed";
+    const r = result.report;
+    const lines = [];
+    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 (result.scaffolded?.length) {
+        lines.push(`  Scaffolded a buildable chant project: ${result.scaffolded.map((f) => basename(f)).join(", ")} (npm install && npm run build).`);
+    }
+    if (result.params?.length) {
+        lines.push(`  Deferred input(s) declared as build params (override with --param <name>=<value>):`);
+        for (const p of result.params) {
+            const def = p.default !== undefined ? `default ${JSON.stringify(p.default)} from state` : "no default (required: false)";
+            lines.push(`    ${p.name} — was ${p.survivor}.${p.attrs.join("/")}; ${def}`);
+        }
+    }
+    if (result.manifestPath) {
+        lines.push(`  State manifest: ${result.manifestPath} — carve bridge/apply pick the target up from here.`);
+    }
+    if (r.carveSet.length > 1) {
+        // Say what each fold actually contributed — announcing the fold without the
+        // properties was the bug behind #1637.
+        const contributed = new Map((result.folded ?? []).map((f) => [f.address, f.props]));
+        const folded = r.carveSet
+            .filter((m) => m.foldedInto)
+            .map((m) => {
+            const props = contributed.get(m.address);
+            if (props === undefined)
+                return m.address;
+            return props.length ? `${m.address} (${props.join(", ")})` : `${m.address} (nothing mappable)`;
+        });
+        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/dist/cli/commands/carve-status.js

@@ -0,0 +1,119 @@
+/**
+ * `chant carve status` — the read over a tree of carve manifests (#2038).
+ *
+ * emit → bridge → apply each persist their step into `<target>.carve.json`
+ * (./../../terraform/manifest.ts), but until now nothing read that state back
+ * over more than one output dir at a time: a renderer wanting "what carves
+ * exist under this project, and how far along is each" had to walk the tree
+ * itself and guess at depth. This makes the walk a contract: recurse from
+ * `--from` (default: cwd), read every manifest the way bridge/apply's own
+ * `resolveCarveManifest` reads one, and answer with each manifest's target,
+ * stage, and path. Read-only — it writes nothing and touches no live resource.
+ */
+import { existsSync, readdirSync, statSync } from "fs";
+import { join, relative, resolve } from "path";
+import { CARVE_MANIFEST_SUFFIX, readCarveManifest, } from "../../terraform/manifest.js";
+/**
+ * Directories that never hold a carve output dir and make the walk expensive
+ * or wrong: dependency trees, VCS internals, build output.
+ */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".chant"]);
+/** Every `*.carve.json` under `root`, found by a bounded recursive walk. */
+function findManifests(root) {
+    const found = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return; // unreadable dir — skip rather than fail the whole status
+        }
+        for (const entry of entries.sort()) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const path = join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(path);
+            }
+            catch {
+                continue; // dangling symlink
+            }
+            if (stat.isDirectory())
+                walk(path);
+            else if (entry.endsWith(CARVE_MANIFEST_SUFFIX))
+                found.push(path);
+        }
+    };
+    walk(root);
+    return found;
+}
+function stageOf(manifest) {
+    if (manifest.apply)
+        return "applied";
+    if (manifest.bridge)
+        return "bridged";
+    if (manifest.emit)
+        return "emitted";
+    return "planned";
+}
+export function carveStatus(opts = {}) {
+    const root = resolve(opts.from ?? process.cwd());
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        return { ok: false, error: `Not a directory: ${root}` };
+    }
+    const carves = [];
+    const unreadable = [];
+    for (const path of findManifests(root)) {
+        const rel = relative(root, path);
+        const manifest = readCarveManifest(path);
+        if (!manifest) {
+            unreadable.push(rel);
+            continue;
+        }
+        carves.push({
+            path: rel,
+            target: manifest.target,
+            ...(manifest.tfType ? { tfType: manifest.tfType } : {}),
+            stage: stageOf(manifest),
+            at: {
+                ...(manifest.emit?.at ? { emit: manifest.emit.at } : {}),
+                ...(manifest.bridge?.at ? { bridge: manifest.bridge.at } : {}),
+                ...(manifest.apply?.at ? { apply: manifest.apply.at } : {}),
+            },
+            ...(manifest.emit ? { emittedFiles: manifest.emit.files } : {}),
+        });
+    }
+    return { ok: true, from: root, carves, ...(unreadable.length > 0 ? { unreadable } : {}) };
+}
+/** The JSON payload `--json` emits — everything but `ok`. */
+export function carveStatusJson(result) {
+    return {
+        from: result.from,
+        carves: result.carves ?? [],
+        ...(result.unreadable ? { unreadable: result.unreadable } : {}),
+    };
+}
+export function formatCarveStatus(result) {
+    const carves = result.carves ?? [];
+    if (carves.length === 0) {
+        return `No carve manifests under ${result.from} — run \`chant carve emit\` first.`;
+    }
+    const L = [];
+    L.push(`${carves.length} carve${carves.length === 1 ? "" : "s"} under ${result.from}`);
+    L.push("");
+    for (const row of carves) {
+        const when = row.at.apply ?? row.at.bridge ?? row.at.emit;
+        L.push(`  ${row.target}  [${row.stage}${when ? ` @ ${when}` : ""}]`);
+        L.push(`    manifest: ${row.path}`);
+        if (row.emittedFiles && row.emittedFiles.length > 0) {
+            L.push(`    emitted:  ${row.emittedFiles.join(", ")}`);
+        }
+    }
+    if (result.unreadable && result.unreadable.length > 0) {
+        L.push("");
+        L.push(`  Unreadable (malformed or unknown version): ${result.unreadable.join(", ")}`);
+    }
+    return L.join("\n");
+}

package/dist/cli/commands/carve.js

@@ -0,0 +1,204 @@
+/**
+ * `chant carve advise` — the read-only peelability advisor (#214, #1056).
+ *
+ * Points at foreign infrastructure and reports which pieces are cheap to carve
+ * into native chant later and which should stay where they are. It emits
+ * nothing, patches nothing, and touches no live resource — pure analysis. The
+ * emit/boundary/apply phases (`carve emit|bridge|apply`, #197) read Terraform
+ * only, and refuse a cloud assembly by name.
+ *
+ * Two sources, one report. A Terraform estate is parsed from `.tf`; a CDK cloud
+ * assembly is read from `cdk.out` (#1056). Which one is in `--from` is decided
+ * by looking, not by a second flag: a directory holding `manifest.json` plus a
+ * synthesized `*.template.json` is an assembly. Both produce the same bands,
+ * the same score arithmetic, and the same JSON shape.
+ */
+import { existsSync, statSync, writeFileSync } from "fs";
+import { adviseCloudAssembly, CDK_DIALECT } from "../../cdk/advise.js";
+import { isCloudAssembly } from "../../cdk/assembly.js";
+import { parseTerraformDir, Hcl2JsonNotInstalled } from "../../terraform/parse.js";
+import { scoreEstate } from "../../terraform/score.js";
+import { boundaryReport } from "../../terraform/carve.js";
+const BAND_ORDER = ["clean leaf", "carvable w/ edits", "leave in Terraform"];
+export async function carveAdvise(opts) {
+    if (!opts.from) {
+        return { ok: false, error: "chant carve advise requires --from <terraform-dir | cdk.out>" };
+    }
+    if (!existsSync(opts.from) || !statSync(opts.from).isDirectory()) {
+        return { ok: false, error: `Not a directory: ${opts.from}` };
+    }
+    const result = isCloudAssembly(opts.from) ? adviseCdk(opts) : await adviseTerraform(opts);
+    if (result.ok && opts.reportFile) {
+        writeFileSync(opts.reportFile, JSON.stringify(carveJson(result), null, 2));
+    }
+    return result;
+}
+/** Rank a CDK cloud assembly. No parser to install, no state file to read. */
+function adviseCdk(opts) {
+    if (opts.statePath) {
+        return {
+            ok: false,
+            error: `${opts.from} is a CDK cloud assembly, and --state is a Terraform option. ` +
+                "A synthesized template already carries its own instance counts.",
+        };
+    }
+    try {
+        const advice = adviseCloudAssembly(opts.from);
+        return {
+            ok: true,
+            from: opts.from,
+            source: "cdk",
+            results: advice.results,
+            graph: advice.graph,
+            scoreOptions: advice.scoreOptions,
+            diagnostics: advice.diagnostics,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Failed to read the CDK cloud assembly in ${opts.from}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+async function adviseTerraform(opts) {
+    if (opts.statePath && !existsSync(opts.statePath)) {
+        return { ok: false, error: `State file not found: ${opts.statePath}` };
+    }
+    try {
+        const graph = await parseTerraformDir(opts.from, { statePath: opts.statePath });
+        return { ok: true, from: opts.from, source: "terraform", results: scoreEstate(graph), graph };
+    }
+    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)}` };
+    }
+}
+/**
+ * The schema version of the `--json` / `--report` payload (#1636).
+ *
+ * The report is a cross-tool contract — behold renders it as a graph — so it
+ * says which shape it is. The promise attached to this number:
+ *
+ *  - **Additive within a version.** New top-level fields, new per-resource
+ *    fields, new kinds of entry in an existing list, and new values in an
+ *    open-ended enum (a `bridge` kind, say) may appear in any release. A
+ *    reader must ignore keys and values it does not know.
+ *  - **A removal, a rename, or a changed meaning bumps it.** So does narrowing
+ *    a field's type (an optional becoming required is additive; the reverse is
+ *    not).
+ *  - A reader that does not know the version it is handed should refuse the
+ *    report rather than half-read it.
+ *
+ * The CDK source (#1056) stays inside that promise and does not bump the
+ * version. Every field an existing reader keys on keeps its type and meaning:
+ * `address` is still an opaque string identifier (a construct path instead of a
+ * Terraform address), `kind` is still `"resource"` or `"module"` (an L3
+ * construct subtree is a Composite candidate, which is what `module` already
+ * means), `score`/`band`/`breakdown` are the same arithmetic. What is new is
+ * additive and ignorable: the top-level `source` discriminator, per-resource
+ * `notes` and `members`, and two more `bridge` values in a list that was
+ * already declared open-ended.
+ */
+export const CARVE_REPORT_VERSION = 1;
+/** Build the `--json` / `--report` payload. */
+export function carveJson(result) {
+    const results = result.results ?? [];
+    const counts = Object.fromEntries(BAND_ORDER.map((b) => [b, results.filter((r) => r.band === b).length]));
+    const source = result.source ?? "terraform";
+    const dialect = source === "cdk" ? CDK_DIALECT : "terraform";
+    return {
+        version: CARVE_REPORT_VERSION,
+        from: result.from,
+        source,
+        advisory: "read-only — emits nothing, patches nothing, touches no live resource",
+        count: results.length,
+        bands: counts,
+        ...(result.diagnostics?.length ? { diagnostics: result.diagnostics } : {}),
+        resources: results.map((r) => withBoundary(r, result.graph, dialect, result.scoreOptions)),
+    };
+}
+/** A scored resource plus its carve boundary, when the graph is at hand (#1636). */
+function withBoundary(r, graph, dialect, score) {
+    if (!graph)
+        return r;
+    const report = boundaryReport(graph, r.address, { dialect, score });
+    if (!report)
+        return r;
+    return { ...r, boundary: { inbound: report.inbound, outbound: report.outbound } };
+}
+/** Human-readable banded, ranked summary. */
+export function formatCarveReport(result) {
+    const results = result.results ?? [];
+    const source = result.source ?? "terraform";
+    const cdk = source === "cdk";
+    if (results.length === 0) {
+        return cdk
+            ? `No carvable constructs found in ${result.from}\n(the assembly synthesized no infrastructure beyond CDK's own scaffolding).`
+            : `No carvable resources found in ${result.from}\n(only data sources, providers, or unsupported types were present).`;
+    }
+    const lines = [];
+    lines.push(`${cdk ? "CDK cloud-assembly" : "Terraform"} carve-out advisory for ${result.from}`);
+    lines.push(`  ${results.length} ${cdk ? "construct(s)" : "resource(s)/module(s)"} scored. ` +
+        "Advises only — nothing is emitted or changed.");
+    for (const note of result.diagnostics ?? [])
+        lines.push(`  ! ${note}`);
+    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, cdk)}  (${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, cdk)}`);
+            for (const note of r.notes ?? [])
+                lines.push(`       ${note}`);
+        }
+        lines.push("");
+    }
+    lines.push(`Bands: 80-100 carve now | 50-79 carve with boundary edits | 0-49 leave in ${cdk ? "CDK" : "Terraform"}`);
+    return lines.join("\n").trimEnd();
+}
+function bandLabel(band, cdk) {
+    switch (band) {
+        case "clean leaf":
+            return "CLEAN LEAF — carve now";
+        case "carvable w/ edits":
+            return "CARVABLE — has boundary work";
+        case "leave in Terraform":
+            // The band's name is part of the JSON contract and does not change per
+            // source; only the heading a person reads does.
+            return cdk ? "LEAVE IN CDK" : "LEAVE IN TERRAFORM";
+    }
+}
+/** One-line explanation of what drove a score, from its breakdown. */
+function reasons(r, cdk = false) {
+    const b = r.breakdown;
+    if (b.tier === null) {
+        return cdk ? "no chant AWS lexicon target for this type" : "no known native mapping (unsupported provider/type)";
+    }
+    // A node that scored 0 with every penalty at 0 was disqualified outright, not
+    // scored down. Reciting the arithmetic would credit terms that never applied;
+    // the stated reason follows on the next line.
+    if (r.score === 0 && Object.values(b.penalties).every((p) => p === 0))
+        return "not carvable as it stands";
+    const parts = [];
+    if (b.inbound)
+        parts.push(`${b.inbound} inbound (${cdk ? "a reimport each" : "data-source patch each"})`);
+    if (b.outputs)
+        parts.push(`${b.outputs} ${cdk ? "stack output(s)" : "output block(s)"} reading it (one-line rewrite 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(cdk ? "condition/parameter present" : "count/for_each/data present");
+    if (b.instances > 1)
+        parts.push(`${b.instances} instances`);
+    if (b.penalties.asset)
+        parts.push("asset-backed");
+    return parts.length ? parts.join(", ") : "clean 1:1 native map, no boundary edges";
+}