@intentius/chant 0.124.12 → 0.124.14

package/dist/terraform/bridge.js

@@ -0,0 +1,204 @@
+/**
+ * Boundary bridging for the strangler-fig carve (#197) — the centerpiece.
+ *
+ * Carving a resource cuts edges. This generates the edits to the Terraform you
+ * LEAVE BEHIND so its plan stays valid once the resource is chant-owned:
+ *
+ *  - inbound edge  → the survivor loses its reference to the carved resource.
+ *    Bridge: add a `data` source for the (now chant-managed) resource and
+ *    rewrite the survivor's `type.name.attr` references to `data.type.name.attr`.
+ *    The provider's data-source shape (`data-source-shape.ts`, #2034) decides
+ *    both halves — the data type and body, and the attribute path survivors
+ *    read through, which need not be the resource's own.
+ *    Required immediately, or `terraform plan` errors on the dangling ref.
+ *    An `output` block reading the carved resource is such a survivor (#1638):
+ *    same data source, same textual rewrite, applied to the output's value.
+ *
+ *  - outbound edge → the carved resource read a value from a survivor. That
+ *    value must enter chant from outside synthesis, as a deploy-time input.
+ *    Deferred until apply; here we only record the provenance.
+ *
+ * Pure text transform over the original `.tf` content — no wasm, no shell, no
+ * mutation. The command layer writes the results and (optionally) diffs them
+ * into a git-applyable patch. A carve never destroys or recreates; the runbook
+ * is reversible via `terraform import`.
+ */
+import { deferredParamName } from "./carve.js";
+import { rewriteReadPath } from "./data-source-shape.js";
+import { exciseResourceBlocks } from "./excise.js";
+/**
+ * `aws_s3_bucket.assets` → a regex matching that reference head plus the
+ * attribute path that follows it, not already `data.`-prefixed. The path is
+ * captured because the data source may expose it under a different attribute:
+ * a survivor reading `kubernetes_manifest.app_config.manifest.data.x` has to
+ * come out as `data.kubernetes_resource.app_config.object.data.x`.
+ */
+function referenceRegex(address) {
+    const escaped = address.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // (?<!data\.) — do not double-prefix an existing data source reference.
+    return new RegExp(`(?<!data\\.)\\b${escaped}\\b((?:\\.[A-Za-z_][A-Za-z0-9_-]*)*)`, "g");
+}
+const IDENTIFY_TODO = "  # TODO: identify the resource (its name/id was interpolated in the source)";
+/** `terraform fmt` aligns the `=` of consecutive assignments; so do we. */
+function alignedAssignments(pairs, indent) {
+    const width = Math.max(...pairs.map(([key]) => key.length));
+    return pairs.map(([key, value]) => `${indent}${key.padEnd(width)} = ${JSON.stringify(value)}`);
+}
+/** Resolved `[name, value]` pairs, or null when a required field has no literal. */
+function resolveFields(fields, values) {
+    const pairs = [];
+    for (const field of fields) {
+        const value = values[field.from];
+        if (value === undefined) {
+            if (field.required)
+                return null;
+            continue;
+        }
+        pairs.push([field.name, value]);
+    }
+    return pairs;
+}
+/**
+ * The `data` block standing in for the carved resource. A shape whose required
+ * arguments the carved block did not supply as literals renders the TODO body
+ * instead of a block `terraform validate` would reject.
+ */
+function dataSourceHcl(shape, name, values) {
+    const body = [];
+    const args = resolveFields(shape.args ?? [], values);
+    if (args === null)
+        return todoBlock(shape.type, name);
+    if (args.length)
+        body.push(...alignedAssignments(args, "  "));
+    for (const block of shape.blocks ?? []) {
+        const fields = resolveFields(block.fields, values);
+        if (fields === null)
+            return todoBlock(shape.type, name);
+        if (!fields.length)
+            continue;
+        if (body.length)
+            body.push("");
+        body.push(`  ${block.name} {`, ...alignedAssignments(fields, "    "), "  }");
+    }
+    if (!body.length)
+        body.push(IDENTIFY_TODO);
+    return `data ${JSON.stringify(shape.type)} ${JSON.stringify(name)} {\n${body.join("\n")}\n}`;
+}
+function todoBlock(type, name) {
+    return `data ${JSON.stringify(type)} ${JSON.stringify(name)} {\n${IDENTIFY_TODO}\n}`;
+}
+/**
+ * Build the bridge plan for a carve.
+ *
+ * @param report    the boundary report (from `boundaryReport`)
+ * @param files     every `.tf` file in the estate, as { path, content }
+ * @param readBacks how each carved address is read back as a data source, and
+ *                  the literals to render it with (`dataSourceShapeOf` +
+ *                  the graph node's `dataSourceValues`)
+ */
+export function generateBridge(report, files, readBacks) {
+    // Carved resources that something still depends on need a data source.
+    const carvedWithInbound = new Map();
+    for (const e of report.inbound) {
+        const [type, ...rest] = e.carved.split(".");
+        carvedWithInbound.set(e.carved, { type, name: rest.join("."), readBack: readBacks.get(e.carved) ?? {} });
+    }
+    const dataSources = [...carvedWithInbound.entries()].map(([address, { type, name, readBack }]) => {
+        const shape = readBack.shape ?? { type };
+        return { address, type: shape.type, name, hcl: dataSourceHcl(shape, name, readBack.values ?? {}) };
+    });
+    // Excise the carve set's own blocks (#998): after `terraform state rm`, a
+    // block left behind would re-create the resource on the next apply. Then
+    // rewrite every remaining survivor reference into a data ref.
+    const exciseTargets = report.carveSet
+        .filter((m) => !m.address.startsWith("module."))
+        .map((m) => {
+        const [type, ...rest] = m.address.split(".");
+        return { address: m.address, type, name: rest.join(".") };
+    });
+    const rewrites = files.map(({ path, content }) => {
+        const excision = exciseResourceBlocks(content, exciseTargets);
+        let rewritten = excision.content;
+        for (const [address, { type, name, readBack }] of carvedWithInbound) {
+            const shape = readBack.shape;
+            const head = `data.${shape?.type ?? type}.${name}`;
+            rewritten = rewritten.replace(referenceRegex(address), (_match, path) => head + rewriteReadPath(shape, path));
+        }
+        return { path, original: content, rewritten, changed: rewritten !== content, excised: excision.excised };
+    });
+    const excised = rewrites.flatMap((r) => r.excised);
+    const deferredInputs = report.outbound.map((e) => {
+        const params = (e.via ?? []).map(deferredParamName);
+        const wiring = params.length
+            ? `emit declares it as build param ${params.map((p) => `\`${p}\``).join(", ")} — override with --param at build`
+            : "supply this as a deploy-time input to the carved component at apply";
+        return {
+            survivor: e.survivor,
+            carved: e.carved,
+            attrs: e.attrs,
+            params,
+            note: `${e.carved} reads ${e.survivor}.${e.attrs.join(", ")} — ${wiring}.`,
+        };
+    });
+    const outputRewrites = report.inbound
+        .filter((e) => e.bridge === "tf-output-rewrite")
+        .map((e) => e.survivor)
+        .sort();
+    return {
+        target: report.target,
+        dataSources,
+        rewrites,
+        deferredInputs,
+        excised,
+        outputRewrites,
+        runbook: buildRunbook(report, dataSources, deferredInputs, excised, outputRewrites),
+    };
+}
+/** The reversible, observe-first handoff runbook (#197). */
+function buildRunbook(report, dataSources, deferred, excised, outputRewrites) {
+    const carvedAddrs = report.carveSet.map((m) => m.address);
+    const L = [];
+    L.push(`# Carve-out: ${report.target} → chant   [observe-first, reversible]`);
+    L.push("");
+    L.push(`Peelability ${report.peelability}. Carves ${carvedAddrs.length} Terraform resource(s) into chant, leaving the live resource untouched.`);
+    L.push("");
+    L.push("## 1. Review the emitted chant source");
+    L.push("    (produced by `chant carve emit` — confirm it builds to a spec-true template)");
+    L.push("");
+    L.push("## 2. Stop Terraform managing the resource (does NOT destroy it)");
+    L.push(`    terraform state rm ${carvedAddrs.join(" ")}`);
+    L.push("");
+    L.push("## 3. Confirm no destroy, then patch the survivors");
+    L.push("    terraform plan   # expect 0 to destroy; refs to the carved resource now error");
+    if (excised.length) {
+        L.push(`    # the generated bridge patch removes the carved block(s): ${excised.join(", ")}`);
+        L.push("    #   (without this, the next apply would re-create what state rm released)");
+    }
+    if (dataSources.length) {
+        L.push("    # it also adds these data sources and rewires references:");
+        for (const ds of dataSources)
+            L.push(`    #   data.${ds.type}.${ds.name}  (for ${ds.address})`);
+    }
+    else if (!excised.length) {
+        L.push("    # no inbound edges — no survivor patch needed.");
+    }
+    if (outputRewrites.length) {
+        L.push(`    # and repoints these output block(s) at the data source: ${outputRewrites.join(", ")}`);
+    }
+    L.push("    terraform plan   # expect: in-place updates to the survivors only");
+    L.push("    terraform apply");
+    L.push("");
+    L.push("## 4. Adopt the live resource into chant (now an orphan)");
+    L.push("    chant carve emit --from <tf-dir> --select " + report.target + " --env <env>   # already done if you ran emit");
+    L.push("    # then apply the ownership marker so chant owns it (carve apply, next step)");
+    if (deferred.length) {
+        L.push("");
+        L.push("## Deferred deploy-time inputs (wire these when you turn the dial to apply)");
+        for (const d of deferred)
+            L.push(`    - ${d.note}`);
+    }
+    L.push("");
+    L.push("## Rollback (any time before apply-graduation)");
+    L.push(`    terraform import ${report.target} <physical-id>   # back under Terraform`);
+    return L.join("\n");
+}

package/dist/terraform/carve-provider.js

@@ -0,0 +1,155 @@
+/**
+ * The carve provider seam (#2016).
+ *
+ * `carve advise|emit|bridge` used to reach into the AWS carve table directly:
+ * the tier map derived from it, the emit gate was `awsCarveType(t) !== undefined`,
+ * the adopter called `applyAwsMapper`, and the emitted project's lexicon was a
+ * constant. A second provider — Kubernetes emit (#999), GCP (#2017) — had
+ * nowhere to land except a parallel path beside the AWS one.
+ *
+ * A provider owns one or more Terraform type prefixes and answers everything
+ * the carve commands ask about the types under them: how each ranks against a
+ * native spec, which HCL attribute carries the physical name, which
+ * sub-resources fold into a parent, which types emit can produce source for,
+ * and how to adopt one from `.tfstate`.
+ *
+ * ── Why the registry lives in core, not behind a `LexiconPlugin` capability ──
+ *
+ * `carve advise` runs against a Terraform directory that is not a chant project:
+ * there is no `chant.config.ts` naming lexicons, so there is nothing to load
+ * plugins from, and `carve emit --state` is deliberately offline (see the
+ * handler). Behind a plugin capability both would have to load plugins to learn
+ * that a type ranks tier 1. Providers are also Terraform-provider knowledge
+ * (`terraform-provider-aws` attribute names), which belongs beside the HCL
+ * parser rather than inside a lexicon.
+ *
+ * `registerCarveProvider` is exported, so a plugin that wants to contribute a
+ * provider at runtime still can — the seam does not foreclose it, it just does
+ * not require plugin loading for the paths that run without one.
+ */
+import { identityAttrShape } from "./data-source-shape.js";
+import { BUILTIN_CARVE_PROVIDERS } from "./providers/index.js";
+/**
+ * A provider declaring emit types without an adopter would accept a type on
+ * `--env` and fail it on `--state`, the advise↔emit cliff #2015 closed.
+ */
+function validate(provider) {
+    if (provider.emitTypes?.length && !provider.adopt) {
+        throw new Error(`Carve provider "${provider.name}" declares emitTypes but no adopt() — the --state path would refuse what --env accepts.`);
+    }
+    if (!provider.tfTypePrefixes.length) {
+        throw new Error(`Carve provider "${provider.name}" claims no Terraform type prefix, so no type would ever resolve to it.`);
+    }
+}
+const providers = [...BUILTIN_CARVE_PROVIDERS];
+for (const p of providers)
+    validate(p);
+/** Bumped on every registry mutation, so the derived indexes rebuild. */
+let revision = 0;
+/**
+ * Register a carve provider. Returns a function that removes it again, so a
+ * test (or a plugin unloading) leaves the registry as it found it.
+ */
+export function registerCarveProvider(provider) {
+    validate(provider);
+    const existing = providers.findIndex((p) => p.name === provider.name);
+    if (existing >= 0)
+        providers.splice(existing, 1);
+    providers.push(provider);
+    revision++;
+    return () => {
+        const at = providers.indexOf(provider);
+        if (at < 0)
+            return;
+        providers.splice(at, 1);
+        revision++;
+    };
+}
+/** Every registered provider, in registration order. */
+export function carveProviders() {
+    return providers;
+}
+let cached = null;
+function index() {
+    if (cached && cached.revision === revision)
+        return cached.index;
+    const built = {
+        prefixes: [],
+        tiers: {},
+        identityAttrs: {},
+        dataSourceShapes: {},
+        foldsInto: {},
+        emitters: new Map(),
+    };
+    for (const provider of providers) {
+        for (const prefix of provider.tfTypePrefixes)
+            built.prefixes.push({ prefix, provider });
+        Object.assign(built.tiers, provider.tiers);
+        if (provider.identityAttrs)
+            Object.assign(built.identityAttrs, provider.identityAttrs);
+        if (provider.dataSourceShapes)
+            Object.assign(built.dataSourceShapes, provider.dataSourceShapes);
+        if (provider.foldsInto)
+            Object.assign(built.foldsInto, provider.foldsInto);
+        for (const tfType of provider.emitTypes ?? [])
+            built.emitters.set(tfType, provider);
+    }
+    built.prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
+    cached = { revision, index: built };
+    return built;
+}
+/** The provider owning this Terraform type, by longest prefix match. */
+export function resolveCarveProvider(tfType) {
+    return index().prefixes.find((p) => tfType.startsWith(p.prefix))?.provider;
+}
+/**
+ * The provider that can emit chant source for this Terraform type. Narrower
+ * than {@link resolveCarveProvider}: a provider owns every type under its
+ * prefix for advise, and only the ones on its `emitTypes` list for emit.
+ */
+export function resolveEmitProvider(tfType) {
+    return index().emitters.get(tfType);
+}
+/** Every Terraform type any registered provider can emit, sorted, for user-facing hints. */
+export function carveEmitTypes() {
+    return [...index().emitters.keys()].sort();
+}
+/** The lexicons emit can adopt into, sorted — what the CLI loads plugins for. */
+export function carveEmitLexicons() {
+    return [...new Set([...index().emitters.values()].map((p) => p.lexicon))].sort();
+}
+/** Terraform resource type → native tier, merged over every provider. Read-only: it is the cached index. */
+export function carveTierMap() {
+    return index().tiers;
+}
+/** The HCL attribute carrying this type's physical name, if its provider declares one. */
+export function carveIdentityAttr(tfType) {
+    return index().identityAttrs[tfType];
+}
+/** The parent Terraform type this sub-resource folds into, if any. */
+export function carveFoldParent(tfType) {
+    return index().foldsInto[tfType];
+}
+/**
+ * How `carve bridge` reads this type back as a `data` source (#2034), or
+ * undefined when it cannot be read back at all — which is what makes
+ * `canBridge` refuse it.
+ *
+ * Resolution order:
+ *  1. a shape the owning provider declared for the type;
+ *  2. otherwise the shape a plain identity attribute implies (same type, one
+ *     required argument) — the path every AWS and google type takes;
+ *  3. otherwise undefined, when the identity attribute is a dotted path into
+ *     nested values and no provider declared a shape for it;
+ *  4. and for a type with no identity attribute at all, the bare data-source
+ *     type: the bridge still emits a block, with a TODO for the body.
+ */
+export function carveDataSourceShape(tfType) {
+    const declared = index().dataSourceShapes[tfType];
+    if (declared)
+        return declared;
+    const attr = index().identityAttrs[tfType];
+    if (attr === undefined)
+        return { type: tfType };
+    return identityAttrShape(tfType, attr);
+}

package/dist/terraform/carve.js

@@ -0,0 +1,138 @@
+/**
+ * Carve-out boundary analysis for the strangler-fig emit path (#197).
+ *
+ * The advisor (#214) ranks *what* is cheap to carve. This is the next step:
+ * given a chosen resource, work out the boundary — every dependency edge the
+ * carve would cut — so the surviving Terraform can be patched and the resource
+ * handed off without destroying it.
+ *
+ * Pure analysis over the graph, like the scorer. Emitting the chant source
+ * (via live import) and generating the TF patches live in the command/bridge
+ * layers; this module just classifies the boundary.
+ */
+import { inboundEdges, outboundEdges } from "./graph.js";
+import { foldParentOf, resolveTier } from "./tier-map.js";
+import { scoreEstate } from "./score.js";
+/**
+ * The carve set for a selected address: the node itself plus any sub-resources
+ * that fold into it (same name, a `foldParentOf` child type whose parent is the
+ * selection). Those are carried along and inlined, not left behind.
+ */
+export function resolveCarveSet(graph, target) {
+    const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
+    const selected = byAddress.get(target);
+    if (!selected)
+        return [];
+    const members = [{ address: selected.address, type: selected.type }];
+    if (selected.kind === "resource" && selected.type) {
+        for (const node of graph.nodes) {
+            if (node.kind !== "resource" || !node.type)
+                continue;
+            const parentType = foldParentOf(node.type);
+            if (parentType === selected.type && node.name === selected.name) {
+                members.push({ address: node.address, type: node.type, foldedInto: selected.address });
+            }
+        }
+    }
+    return members;
+}
+/** The bridge patch an inbound cut needs, per source. */
+function inboundBridge(dialect, fromOutput) {
+    if (dialect === "cdk")
+        return fromOutput ? "cfn-output-rewrite" : "cdk-import";
+    return fromOutput ? "tf-output-rewrite" : "tf-data-source";
+}
+/**
+ * Classify the boundary of carving `target`: the inbound edges that need an
+ * immediate data-source patch, and the outbound edges that become deferred
+ * deploy-time inputs. Edges internal to the carve set (e.g. a folded
+ * sub-resource pointing at its parent) are not boundary work.
+ */
+export function boundaryReport(graph, target, opts = {}) {
+    const dialect = opts.dialect ?? "terraform";
+    const carveSet = resolveCarveSet(graph, target);
+    if (carveSet.length === 0)
+        return null;
+    const inSet = new Set(carveSet.map((m) => m.address));
+    const inbound = [];
+    const outbound = [];
+    for (const member of carveSet) {
+        for (const e of inboundEdges(graph, member.address)) {
+            if (inSet.has(e.from))
+                continue; // internal edge
+            inbound.push({
+                direction: "inbound",
+                survivor: e.from,
+                carved: e.to,
+                attrs: e.attrs,
+                via: e.via,
+                bridge: inboundBridge(dialect, e.fromKind === "output"),
+                required: "immediately",
+                ...(e.crossStack ? { crossStack: true } : {}),
+            });
+        }
+        for (const e of outboundEdges(graph, member.address)) {
+            if (inSet.has(e.to))
+                continue; // internal edge
+            outbound.push({
+                direction: "outbound",
+                survivor: e.to,
+                carved: e.from,
+                attrs: e.attrs,
+                via: e.via,
+                bridge: "deferred-input",
+                required: "at-apply",
+                ...(e.crossStack ? { crossStack: true } : {}),
+            });
+        }
+    }
+    const score = scoreEstate(graph, opts.score).find((r) => r.address === target);
+    const diagnostics = [];
+    const tierOf = opts.score?.tierOf ?? resolveTier;
+    if (carveSet[0].type &&
+        tierOf(carveSet[0].type) === null &&
+        graph.nodes.find((n) => n.address === target)?.kind === "resource") {
+        diagnostics.push(`No known native mapping for ${carveSet[0].type} — emit will have no target type.`);
+    }
+    return {
+        target,
+        carveSet,
+        peelability: score?.score ?? 0,
+        inbound: dedupeEdges(inbound),
+        outbound: dedupeEdges(outbound),
+        reversible: true,
+        diagnostics,
+    };
+}
+/**
+ * The build-parameter name a deferred input's carrying attribute becomes on
+ * emit (#998) — shared so bridge notes and emitted `buildParams` agree.
+ */
+export function deferredParamName(tfAttr) {
+    return tfAttr.replace(/\W+/g, "_");
+}
+/**
+ * Collapse duplicate edges (same survivor/carved pair), merging attrs.
+ *
+ * The map key below joins the two addresses with U+001F (unit separator).
+ * A Terraform address is built from HCL identifiers plus `.`, `[`, `]`, `"`
+ * and `-`; it cannot contain a C0 control character, so U+001F can never
+ * collide with an address component. Keep it that way — this key is never
+ * serialized, so a plain, non-printing separator is fine, but it must stay
+ * a character no address can produce.
+ */
+export function dedupeEdges(edges) {
+    const byKey = new Map();
+    for (const e of edges) {
+        const key = `${e.survivor}${e.carved}`;
+        const prev = byKey.get(key);
+        if (prev) {
+            prev.attrs = [...new Set([...prev.attrs, ...e.attrs])].sort();
+            prev.via = [...new Set([...prev.via, ...e.via])].sort();
+        }
+        else {
+            byKey.set(key, { ...e, attrs: [...e.attrs], via: [...e.via] });
+        }
+    }
+    return [...byKey.values()].sort((a, b) => (a.survivor < b.survivor ? -1 : a.survivor > b.survivor ? 1 : 0));
+}

package/dist/terraform/data-source-shape.js

@@ -0,0 +1,57 @@
+/**
+ * How a carved Terraform type is read back as a `data` source (#2034).
+ *
+ * `carve bridge` replaces a carved resource with a data source the survivors
+ * read instead. Until now a carve provider said only which attribute carries
+ * the physical name (`identityAttrs`), and the bridge assumed the data source
+ * was the same type as the resource, with that one attribute in its body:
+ *
+ *     data "aws_s3_bucket" "assets" { bucket = "myapp-assets-prod" }
+ *
+ * That assumption holds for AWS and google, and breaks for Kubernetes twice
+ * over. `kubernetes_manifest` names itself by `manifest.metadata.name`, a path
+ * into a nested value that a flat `attr = value` body cannot express; and the
+ * kubernetes provider ships no `kubernetes_manifest` data source at all
+ * (verified against hashicorp/kubernetes v3.2.1: 27 data sources, none a
+ * manifest). Its generic read is `data "kubernetes_resource"`, with a
+ * different type, different arguments, a nested `metadata` block, and its own
+ * attribute path for survivors to read through.
+ *
+ * So a provider contributes a *shape*: the data-source type, where each
+ * argument comes from in the carved body, and how a survivor's attribute path
+ * translates. An identity attribute is one instance of that shape
+ * ({@link identityAttrShape}), so nothing that bridges today changes.
+ */
+/**
+ * The shape a plain identity attribute implies: the same type as the resource,
+ * one required argument, no path translation. Returns undefined for a dotted
+ * attribute, which is a path into nested values and needs a declared shape.
+ */
+export function identityAttrShape(tfType, attr) {
+    if (attr.includes("."))
+        return undefined;
+    return { type: tfType, args: [{ name: attr, from: attr, required: true }] };
+}
+/** Every source path the shape reads, for the graph to resolve out of the carved block. */
+export function shapeSourcePaths(shape) {
+    const paths = (shape.args ?? []).map((f) => f.from);
+    for (const block of shape.blocks ?? [])
+        for (const f of block.fields)
+            paths.push(f.from);
+    return [...new Set(paths)];
+}
+/**
+ * Translate a survivor's attribute path onto the data source. `path` is the
+ * text after the address, leading dot included (`.manifest.data.log_level`) or
+ * empty. Only the first segment is mapped: everything under it is the object's
+ * own structure, which the data source reproduces.
+ */
+export function rewriteReadPath(shape, path) {
+    if (!path || !shape?.readAttrs)
+        return path;
+    const [head, ...rest] = path.slice(1).split(".");
+    const mapped = shape.readAttrs[head];
+    if (mapped === undefined)
+        return path;
+    return `.${[mapped, ...rest].join(".")}`;
+}

package/dist/terraform/emit-source.js

@@ -0,0 +1,36 @@
+/**
+ * Source rendering shared by constructor-shaped carve providers (#2016).
+ *
+ * A provider that adopts into a typed chant constructor call — aws today, gcp
+ * next (#2017) — renders the same literal: an import, an exported `new Ctor({
+ * ...props })`, and a reference comment carrying whatever the mapping could not
+ * place. Only the lexicon import path and the property mapping differ, so the
+ * rendering lives here rather than being copied per provider.
+ *
+ * A provider whose native shape is not a constructor call (a Kubernetes
+ * manifest, #999) renders its own source and does not use this.
+ */
+/** The core subpath the emitted source reads build parameters from. */
+export const PARAMS_IMPORT = "@intentius/chant/params";
+/** Marker for a prop whose value is a `params.<name>` reference, not a literal. */
+export class ParamRef {
+    constructor(name, type) {
+        this.name = name;
+        this.type = type;
+    }
+}
+/** Render a JS object literal with stable key order and given indent. */
+export function renderObject(obj, indent) {
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return "{}";
+    const pad = " ".repeat(indent);
+    const body = keys
+        .map((k) => `${pad}${k}: ${renderValue(obj[k])},`)
+        .join("\n");
+    return `{\n${body}\n}`;
+}
+/** A prop value: a `params.<name>` reference (cast keeps the project tsc-clean) or a literal. */
+export function renderValue(value) {
+    return value instanceof ParamRef ? `params.${value.name} as ${value.type}` : JSON.stringify(value);
+}