@intentius/chant 0.124.13 → 0.124.14

package/dist/terraform/score.js

@@ -0,0 +1,151 @@
+/**
+ * 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
+ *     -  4 * outputs          # an output block reads this → a one-line rewrite (#1638)
+ *     - 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)
+ *
+ * An `output` block referencing the target is a real inbound dependency — the
+ * surviving plan errors on the dangling reference — so it cannot score as
+ * free. It is not a data-source patch either: bridging it rewrites one
+ * expression in a block that manages no infrastructure, the same order of work
+ * as recording an outbound deferred input. Hence 4, not 12.
+ *
+ * Sub-resources that inline into a parent (see `foldParentOf`) 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.
+ *
+ * The model itself is not Terraform-specific — the CDK cloud-assembly advisor
+ * (#1056) scores construct units with the same arithmetic. What differs per
+ * source is the type→tier lookup and the extra signals that source can see, so
+ * both are injectable via `ScoreOptions` rather than forked into a second
+ * scorer. Everything else — the six penalty terms, the clamp, the bands — is
+ * shared verbatim.
+ */
+import { inboundEdges, outboundEdges } from "./graph.js";
+import { foldParentOf, resolveTier } from "./tier-map.js";
+const clamp = (n) => Math.max(0, Math.min(100, n));
+/**
+ * `-12 * 0` is `-0`, and JSON has no notation for it — a report written to a
+ * file would not equal the one held in memory. A term that costs nothing is 0.
+ */
+const term = (n) => (n === 0 ? 0 : n);
+export function bandFor(score) {
+    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;
+/**
+ * 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) {
+    const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+    const folded = new Set();
+    const childrenOf = new Map();
+    for (const node of graph.nodes) {
+        if (node.kind !== "resource" || !node.type)
+            continue;
+        const parentType = foldParentOf(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, graph, foldedChildren, opts) {
+    // Inbound excludes edges from this node's own folded sub-resources, and
+    // counts output blocks separately — they cost less to bridge (#1638).
+    const inboundAll = inboundEdges(graph, node.address).filter((e) => !foldedChildren.has(e.from));
+    const inbound = inboundAll.filter((e) => e.fromKind !== "output").length;
+    const outputs = inboundAll.length - inbound;
+    const outbound = outboundEdges(graph, node.address).length;
+    const signals = opts.signalsFor?.(node) ?? {};
+    const extra = { ...(signals.penalties ?? {}) };
+    const trimmings = {
+        ...(signals.notes?.length ? { notes: signals.notes } : {}),
+        ...(signals.members?.length ? { members: signals.members } : {}),
+    };
+    const tierOf = opts.tierOf ?? resolveTier;
+    const tierInfo = node.kind === "module" ? { tier: MODULE_TIER, mapsTo: undefined } : node.type ? tierOf(node.type) : null;
+    const tier = tierInfo ? tierInfo.tier : null;
+    // Unsupported provider/type, or a source-specific disqualification → 0, no
+    // partial credit. The extra penalties are dropped with the rest of the
+    // arithmetic: there is no score left for them to reduce.
+    if (tier === null || signals.disqualified) {
+        return {
+            address: node.address,
+            kind: node.kind,
+            score: 0,
+            band: "leave in Terraform",
+            ...(tier === null ? {} : { mapsTo: tierInfo && "mapsTo" in tierInfo ? tierInfo.mapsTo : undefined }),
+            breakdown: {
+                inbound,
+                outbound,
+                outputs,
+                tier,
+                hasDynamic: node.hasDynamic,
+                instances: node.instances,
+                penalties: { inbound: 0, outbound: 0, outputs: 0, tier: 0, dynamic: 0, instances: 0 },
+            },
+            ...trimmings,
+            ...(signals.disqualified ? { notes: [signals.disqualified, ...(signals.notes ?? [])] } : {}),
+        };
+    }
+    const penalties = {
+        inbound: term(-12 * inbound),
+        outbound: term(-4 * outbound),
+        outputs: term(-4 * outputs),
+        tier: term(-15 * (tier - 1)),
+        dynamic: node.hasDynamic ? -10 : 0,
+        instances: term(-3 * Math.max(0, node.instances - 1)),
+        ...Object.fromEntries(Object.entries(extra).map(([key, value]) => [key, term(value)])),
+    };
+    const score = clamp(100 + Object.values(penalties).reduce((sum, n) => sum + n, 0));
+    return {
+        address: node.address,
+        kind: node.kind,
+        score,
+        band: bandFor(score),
+        mapsTo: tierInfo && "mapsTo" in tierInfo ? tierInfo.mapsTo : undefined,
+        breakdown: {
+            inbound,
+            outbound,
+            outputs,
+            tier,
+            hasDynamic: node.hasDynamic,
+            instances: node.instances,
+            penalties,
+        },
+        ...trimmings,
+    };
+}
+/**
+ * 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, opts = {}) {
+    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(), opts))
+        .sort((a, b) => b.score - a.score || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
+}

package/dist/terraform/state.js

@@ -0,0 +1,67 @@
+/**
+ * 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";
+/**
+ * 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, address) {
+    const state = JSON.parse(readFileSync(statePath, "utf-8"));
+    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) {
+    const raw = readFileSync(statePath, "utf-8");
+    const state = JSON.parse(raw);
+    const counts = new Map();
+    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, counts) {
+    for (const node of graph.nodes) {
+        const n = counts.get(node.address);
+        if (n !== undefined)
+            node.instances = Math.max(1, n);
+    }
+    return graph;
+}

package/dist/terraform/tier-map.js

@@ -0,0 +1,74 @@
+/**
+ * Terraform-type → native-spec ranking for the carve-out advisor (#214 T3),
+ * resolved through the carve provider registry (`carve-provider.ts`, #2016).
+ *
+ * Every entry comes from a registered provider: the AWS ones from the single
+ * AWS carve-out table (`providers/aws.ts` over `aws-resources.ts`), so the
+ * advisor ranks exactly the AWS types `carve emit` can produce — no advise↔emit
+ * cliff — and the Kubernetes ones from `providers/kubernetes.ts`, which emits
+ * `kubernetes_manifest` and ranks the typed provider resources it does not.
+ *
+ *   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
+ *
+ * These are functions, not frozen constants: the registry is open, so a
+ * provider registered after module load has to be visible here.
+ */
+import { carveDataSourceShape, carveFoldParent, carveIdentityAttr, carveTierMap, resolveEmitProvider, } from "./carve-provider.js";
+export { carveEmitTypes } from "./carve-provider.js";
+/** TF resource type → native tier, over every registered provider. Absent = unsupported (score 0). */
+export function tierMap() {
+    return carveTierMap();
+}
+export function resolveTier(tfType) {
+    return carveTierMap()[tfType] ?? null;
+}
+/**
+ * The HCL attribute carrying a resource's physical name. A dotted entry is a
+ * path into nested blocks (`manifest.metadata.name`). Used for the graph's
+ * identity and the live-import hint. Absent → fall back to the TF logical name.
+ */
+export function identityAttrOf(tfType) {
+    return carveIdentityAttr(tfType);
+}
+/**
+ * The parent Terraform type a sub-resource folds into, if any. Terraform splits
+ * configuration the native spec keeps in one resource; a sub-resource sharing
+ * its parent's name carves with the parent rather than being ranked on its own.
+ */
+export function foldParentOf(tfType) {
+    return carveFoldParent(tfType);
+}
+/**
+ * Can `chant carve emit` produce chant source for this type? Narrower than
+ * `resolveTier`: providers also rank types no emit path can adopt (the typed
+ * `kubernetes_*` resources, whose manifest only the provider schema knows how
+ * to reassemble). Both emit paths — `--state` and `--env` — gate on this, so a
+ * type either command refuses is refused by the other with the same message.
+ */
+export function canCarveEmit(tfType) {
+    return resolveEmitProvider(tfType) !== undefined;
+}
+/**
+ * How `chant carve bridge` reads this type back as a `data` source: the
+ * data-source type, where each argument comes from in the carved body, and how
+ * a survivor's attribute path translates (#2034). Undefined when the type
+ * cannot be read back at all.
+ */
+export function dataSourceShapeOf(tfType) {
+    return carveDataSourceShape(tfType);
+}
+/**
+ * Can `chant carve bridge` render a Terraform `data` source for this type?
+ * True whenever its provider contributes a shape — declared, or implied by a
+ * plain identity attribute. False for a dotted identity attribute with no
+ * declared shape: that is a path into nested values, and a flat `attr = value`
+ * body cannot express it (`manifest.metadata.name = "x"` is not valid HCL). A
+ * type with no identity attribute at all still bridges; the bridge writes a
+ * TODO comment for the body.
+ */
+export function canBridge(tfType) {
+    return carveDataSourceShape(tfType) !== undefined;
+}

package/dist/terraform/types.js

@@ -0,0 +1,13 @@
+/**
+ * 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
+ * `@cdktn/hcl2json` produces (see `parse.ts`), so the graph and scoring can
+ * be tested without loading the wasm parser.
+ */
+export {};

package/dist/terraform/unified-diff.js

@@ -0,0 +1,132 @@
+/**
+ * Minimal unified-diff generator for the carve bridge patch (#998). Emits
+ * git-applyable hunks (`git apply`, or plain `patch -p1`) so the whole survivor
+ * edit — data sources plus rewired references — lands in one reviewable file.
+ * LCS-based; bridge inputs are hand-sized `.tf` files, so O(n·m) is fine.
+ */
+/** One file's diff, `a/<path>` → `b/<path>`, with git headers. Empty when unchanged. */
+export function unifiedDiff(path, oldText, newText, context = 3) {
+    if (oldText === newText)
+        return "";
+    const oldLines = splitLines(oldText);
+    const newLines = splitLines(newText);
+    const ops = diffOps(oldLines.lines, newLines.lines);
+    const hunks = buildHunks(ops, context);
+    if (hunks.length === 0)
+        return "";
+    const L = [];
+    L.push(`diff --git a/${path} b/${path}`);
+    L.push(`--- a/${path}`);
+    L.push(`+++ b/${path}`);
+    for (const hunk of hunks) {
+        L.push(`@@ -${hunkRange(hunk.oldStart, hunk.oldCount)} +${hunkRange(hunk.newStart, hunk.newCount)} @@`);
+        for (const op of hunk.ops) {
+            L.push(`${op.kind === "add" ? "+" : op.kind === "del" ? "-" : " "}${op.line}`);
+            if (op.kind !== "add" && op.oldIndex === oldLines.lines.length - 1 && !oldLines.trailingNewline) {
+                L.push("\");
+            }
+            if (op.kind !== "del" && op.newIndex === newLines.lines.length - 1 && !newLines.trailingNewline) {
+                L.push("\");
+            }
+        }
+    }
+    return L.join("\n") + "\n";
+}
+/** A new-file diff (`/dev/null` → `b/<path>`), git-applyable. */
+export function newFileDiff(path, text) {
+    const { lines, trailingNewline } = splitLines(text);
+    const L = [];
+    L.push(`diff --git a/${path} b/${path}`);
+    L.push("new file mode 100644");
+    L.push("--- /dev/null");
+    L.push(`+++ b/${path}`);
+    if (lines.length > 0) {
+        L.push(`@@ -0,0 +${hunkRange(1, lines.length)} @@`);
+        for (const line of lines)
+            L.push(`+${line}`);
+        if (!trailingNewline)
+            L.push("\");
+    }
+    return L.join("\n") + "\n";
+}
+function hunkRange(start, count) {
+    return count === 1 ? String(start) : `${count === 0 ? start - 1 : start},${count}`;
+}
+function splitLines(text) {
+    if (text === "")
+        return { lines: [], trailingNewline: true };
+    const trailingNewline = text.endsWith("\n");
+    const lines = text.split("\n");
+    if (trailingNewline)
+        lines.pop();
+    return { lines, trailingNewline };
+}
+/** Line-level LCS diff as a flat op list. */
+function diffOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = LCS length of a[i..] and b[j..]
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ kind: "keep", line: a[i], oldIndex: i, newIndex: j });
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ kind: "del", line: a[i], oldIndex: i, newIndex: j });
+            i++;
+        }
+        else {
+            ops.push({ kind: "add", line: b[j], oldIndex: i, newIndex: j });
+            j++;
+        }
+    }
+    for (; i < n; i++)
+        ops.push({ kind: "del", line: a[i], oldIndex: i, newIndex: j });
+    for (; j < m; j++)
+        ops.push({ kind: "add", line: b[j], oldIndex: i, newIndex: j });
+    return ops;
+}
+/** Group change ops into hunks with `context` lines of surrounding keeps. */
+function buildHunks(ops, context) {
+    const changed = ops.map((op) => op.kind !== "keep");
+    const include = new Array(ops.length).fill(false);
+    for (let k = 0; k < ops.length; k++) {
+        if (!changed[k])
+            continue;
+        for (let c = Math.max(0, k - context); c <= Math.min(ops.length - 1, k + context); c++) {
+            include[c] = true;
+        }
+    }
+    const hunks = [];
+    let k = 0;
+    while (k < ops.length) {
+        if (!include[k]) {
+            k++;
+            continue;
+        }
+        const start = k;
+        while (k < ops.length && include[k])
+            k++;
+        const slice = ops.slice(start, k);
+        const oldOps = slice.filter((op) => op.kind !== "add");
+        const newOps = slice.filter((op) => op.kind !== "del");
+        hunks.push({
+            oldStart: (oldOps[0]?.oldIndex ?? slice[0].oldIndex) + 1,
+            oldCount: oldOps.length,
+            newStart: (newOps[0]?.newIndex ?? slice[0].newIndex) + 1,
+            newCount: newOps.length,
+            ops: slice,
+        });
+    }
+    return hunks;
+}