@intentius/chant 0.124.13 → 0.124.15

package/dist/terraform/hcl2json.js

@@ -0,0 +1,60 @@
+/**
+ * The optional HCL parser, loaded lazily. Kept apart from `parse.ts` so a
+ * caller that only needs the loader (the terraform lexicon's HCL reader) does
+ * not pull in the dependency graph, the state reader and the carve tables.
+ *
+ * `@cdktn/hcl2json` is NOT a chant dependency: it carries a ~1.8 MB wasm blob
+ * and only HCL users need it. If it is absent the loader fails with a
+ * one-line install hint.
+ */
+import { appendFileSync } from "fs";
+export class Hcl2JsonNotInstalled extends Error {
+    constructor(cause) {
+        super("Terraform carve-out needs the HCL parser, which is not installed.\n" +
+            "  Install it once:  npm install -D @cdktn/hcl2json\n" +
+            `(underlying error: ${cause instanceof Error ? cause.message : String(cause)})`);
+        this.name = "Hcl2JsonNotInstalled";
+    }
+}
+/**
+ * The environment variable that turns on parser-input recording (chant #2483).
+ *
+ * When set to a file path, every `parse(filename, source)` and every
+ * `getReferencesInExpression(filename, expression)` this process makes is
+ * appended to that file as one JSON line before the real call runs. That is
+ * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
+ * test suite parses, which no corpus walk on disk would find: run the suite
+ * with this set, then replay the file through two parsers and compare. Off
+ * unless set, and never changes a result.
+ */
+export const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
+function recording(parser, path) {
+    const note = (line) => {
+        appendFileSync(path, `${JSON.stringify(line)}\n`);
+    };
+    return {
+        parse: (filename, hcl) => {
+            note({ kind: "parse", filename, text: hcl });
+            return parser.parse(filename, hcl);
+        },
+        getReferencesInExpression: (filename, expression) => {
+            note({ kind: "refs", filename, text: expression });
+            return parser.getReferencesInExpression(filename, expression);
+        },
+    };
+}
+/**
+ * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
+ * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
+ */
+export async function loadHcl2json() {
+    let parser;
+    try {
+        parser = (await import("@cdktn/hcl2json"));
+    }
+    catch (err) {
+        throw new Hcl2JsonNotInstalled(err);
+    }
+    const record = process.env[HCL2JSON_RECORD_ENV];
+    return record ? recording(parser, record) : parser;
+}

package/dist/terraform/manifest.js

@@ -0,0 +1,149 @@
+/**
+ * The carve state manifest (#998) — what makes emit → bridge → apply compose.
+ *
+ * `carve emit` persists the boundary report and adoption selector next to the
+ * emitted source as `<target>.carve.json`. The later steps read it back from
+ * their output dir, so `carve bridge` and `carve apply` no longer need the
+ * target re-specified by hand, and each step records what it did for the next.
+ * Plain JSON on disk — reviewable, diffable, nothing proprietary.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { isAbsolute, join, relative, resolve } from "path";
+export const CARVE_MANIFEST_SUFFIX = ".carve.json";
+/**
+ * Version 2 (#2039): `emit.files`, `bridge.written`, `bridge.patch` and
+ * `apply.stampedFiles` are recorded relative to the manifest's own directory,
+ * so the manifest stays true when the tree is copied, moved, or checked out
+ * elsewhere. Version-1 manifests recorded them absolute; readers resolve
+ * either through `resolveManifestFilePath`.
+ */
+export const CARVE_MANIFEST_VERSION = 2;
+/** Filesystem-safe slug for a Terraform address (shared file-naming convention). */
+export function carveSlug(target) {
+    return target.replace(/[^A-Za-z0-9_]+/g, "-");
+}
+/** Where the manifest for `target` lives inside an output dir. */
+export function carveManifestPath(outDir, target) {
+    return join(outDir, `${carveSlug(target)}${CARVE_MANIFEST_SUFFIX}`);
+}
+/**
+ * Relative-to-`outDir` spelling of a recorded file path. Absolute entries
+ * (the run-time spelling every step naturally produces, and every version-1
+ * manifest on disk) are rewritten against the RESOLVED outDir — a caller's
+ * relative `--output` must not change what "relative to the manifest's
+ * directory" means (#2059). Already-relative entries pass through: they can
+ * only have come from a reader honouring the contract, and re-basing them
+ * against an unknowable original cwd would corrupt, not normalize.
+ */
+function relativizePath(outDir, p) {
+    return isAbsolute(p) ? relative(resolve(outDir), p) : p;
+}
+/**
+ * Normalize a manifest to the version-2 on-disk contract: recorded file
+ * paths relative to the manifest's own directory (#2039). `from` and
+ * `statePath` stay absolute — they locate the Terraform estate, a different
+ * tree the manifest does not travel with.
+ */
+function normalizeManifest(outDir, manifest) {
+    const out = { ...manifest, version: CARVE_MANIFEST_VERSION };
+    if (manifest.emit) {
+        out.emit = { ...manifest.emit, files: manifest.emit.files.map((f) => relativizePath(outDir, f)) };
+    }
+    if (manifest.bridge) {
+        out.bridge = {
+            ...manifest.bridge,
+            written: manifest.bridge.written.map((f) => relativizePath(outDir, f)),
+            ...(manifest.bridge.patch !== undefined ? { patch: relativizePath(outDir, manifest.bridge.patch) } : {}),
+        };
+    }
+    if (manifest.apply?.stampedFiles) {
+        out.apply = { ...manifest.apply, stampedFiles: manifest.apply.stampedFiles.map((f) => relativizePath(outDir, f)) };
+    }
+    return out;
+}
+/**
+ * Resolve a manifest-recorded file path against the manifest's directory.
+ * Absolute paths (version-1 manifests) pass through untouched, so both
+ * on-disk spellings read the same.
+ */
+export function resolveManifestFilePath(manifestDir, p) {
+    // Always ABSOLUTE (#2059): `join` with a relative manifestDir produced a
+    // cwd-relative path, which `relativizePath` then passed through untouched —
+    // so `carve apply --output carveout` recorded `stampedFiles` relative to
+    // wherever the command happened to run, two spellings in one manifest.
+    return isAbsolute(p) ? p : resolve(manifestDir, p);
+}
+/** Write (or overwrite) a manifest into the output dir. Returns the path. */
+export function writeCarveManifest(outDir, manifest) {
+    mkdirSync(outDir, { recursive: true });
+    const path = carveManifestPath(outDir, manifest.target);
+    writeFileSync(path, JSON.stringify(normalizeManifest(outDir, manifest), null, 2) + "\n");
+    return path;
+}
+/** Read a manifest, or null when absent/unreadable/not a known-version manifest. */
+export function readCarveManifest(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed?.version !== 1 && parsed?.version !== 2)
+            return null;
+        if (typeof parsed.target !== "string" || typeof parsed.boundary !== "object")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** All carve manifest paths in an output dir. */
+export function listCarveManifests(outDir) {
+    if (!existsSync(outDir))
+        return [];
+    return readdirSync(outDir)
+        .filter((f) => f.endsWith(CARVE_MANIFEST_SUFFIX))
+        .map((f) => join(outDir, f))
+        .sort();
+}
+/**
+ * Resolve the manifest a later carve step composes with. With a selected
+ * target, that target's manifest (absent is fine — the step just runs
+ * standalone). Without one, the single manifest in the output dir; none or
+ * several is an error naming what is (or is not) there.
+ */
+export function resolveCarveManifest(outDir, select) {
+    if (select) {
+        const path = carveManifestPath(outDir, select);
+        const manifest = readCarveManifest(path);
+        return manifest ? { manifest, path } : {};
+    }
+    const paths = listCarveManifests(outDir);
+    if (paths.length === 0) {
+        return { error: `No carve manifest in ${outDir} — run \`chant carve emit\` first, or pass --select <tf-address>.` };
+    }
+    const manifests = paths
+        .map((path) => ({ path, manifest: readCarveManifest(path) }))
+        .filter((m) => m.manifest !== null);
+    if (manifests.length === 0) {
+        return { error: `No readable carve manifest in ${outDir} — pass --select <tf-address>.` };
+    }
+    if (manifests.length > 1) {
+        const targets = manifests.map((m) => m.manifest.target).join(", ");
+        return { error: `Several carves in ${outDir} (${targets}) — pass --select <tf-address> to pick one.` };
+    }
+    return { manifest: manifests[0].manifest, path: manifests[0].path };
+}
+/**
+ * Read-modify-write a section of an existing manifest. No-op when absent.
+ * The whole manifest is re-normalized on write, so updating a version-1
+ * manifest also migrates its recorded paths to the relative contract.
+ */
+export function updateCarveManifest(outDir, target, patch) {
+    const path = carveManifestPath(outDir, target);
+    const manifest = readCarveManifest(path);
+    if (!manifest)
+        return undefined;
+    Object.assign(manifest, patch);
+    writeFileSync(path, JSON.stringify(normalizeManifest(outDir, manifest), null, 2) + "\n");
+    return path;
+}

package/dist/terraform/parse.js

@@ -0,0 +1,81 @@
+/**
+ * Thin wasm glue for the carve-out advisor (#214 T1): read a Terraform estate's
+ * `.tf` files, run them through `@cdktn/hcl2json`, merge into one tree, and hand
+ * off to the pure `buildGraph`. The parser loader lives in `./hcl2json`, which
+ * this module re-exports.
+ */
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { buildGraph, collectExpressions } from "./graph.js";
+import { readStateInstanceCounts, applyStateCounts } from "./state.js";
+import { loadHcl2json } from "./hcl2json.js";
+export { loadHcl2json, Hcl2JsonNotInstalled, HCL2JSON_RECORD_ENV, } from "./hcl2json.js";
+/**
+ * Resolve every interpolated string in the merged tree through the parser's
+ * expression AST (`getReferencesInExpression`), producing the accessor map
+ * `buildGraph` classifies. The AST — not a regex over the expression body —
+ * decides what is a reference, so a quoted address used as a map key or an
+ * escaped `$${...}` literal yields none. An expression the AST cannot parse in
+ * isolation resolves to no references (fewer edges, never a phantom one).
+ */
+async function resolveExpressionRefs(hcl2json, tree) {
+    const refs = new Map();
+    for (const expr of collectExpressions(tree)) {
+        try {
+            const found = await hcl2json.getReferencesInExpression("expression.tf", expr);
+            refs.set(expr, found.map((r) => r.value));
+        }
+        catch {
+            refs.set(expr, []);
+        }
+    }
+    return refs;
+}
+/** Deep-merge hcl2json trees across files (resource/module/data/output/locals namespaces). */
+function mergeTrees(into, next) {
+    for (const section of ["resource", "data"]) {
+        const src = next[section];
+        if (!src)
+            continue;
+        const dst = (into[section] ?? (into[section] = {}));
+        for (const [type, named] of Object.entries(src)) {
+            dst[type] = { ...(dst[type] ?? {}), ...named };
+        }
+    }
+    if (next.module)
+        into.module = { ...(into.module ?? {}), ...next.module };
+    // Outputs usually live in their own file (#1638) — merge them, or the graph
+    // never sees the estate's outputs.tf at all.
+    if (next.output)
+        into.output = { ...(into.output ?? {}), ...next.output };
+    // `locals` is an array of blocks, not a keyed namespace, so files concatenate
+    // rather than overwrite — a `locals` block in every .tf is idiomatic (#2324).
+    if (next.locals)
+        into.locals = [...(into.locals ?? []), ...next.locals];
+}
+/** List every `.tf` file directly under `dir` (non-recursive; matches Terraform's own module scoping). */
+function listTfFiles(dir) {
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".tf"))
+        .map((f) => join(dir, f))
+        .sort();
+}
+/**
+ * Parse a Terraform directory into a dependency graph. Reads only `.tf` unless
+ * `statePath` is given. Pure `.tf` estates parse fully; `count`/`for_each`
+ * blocks report a single instance and are flagged `hasDynamic`. With state, the
+ * instance counts become accurate (see `state.ts`).
+ */
+export async function parseTerraformDir(dir, opts = {}) {
+    const hcl2json = await loadHcl2json();
+    const files = listTfFiles(dir);
+    const merged = {};
+    for (const file of files) {
+        const tree = await hcl2json.parse(file, readFileSync(file, "utf-8"));
+        mergeTrees(merged, tree);
+    }
+    const graph = buildGraph(merged, await resolveExpressionRefs(hcl2json, merged));
+    if (opts.statePath)
+        applyStateCounts(graph, readStateInstanceCounts(opts.statePath));
+    return graph;
+}

package/dist/terraform/providers/aws.js

@@ -0,0 +1,146 @@
+/**
+ * The AWS carve provider (#2016) — the seam's implementation over the AWS
+ * carve-out table (`../aws-resources.ts`), which stays the single source of
+ * truth for which AWS Terraform types chant can carve and how.
+ *
+ * chant AWS constructors take CloudFormation PascalCase properties (e.g.
+ * `new Bucket({ BucketName })`), while Terraform state uses the provider's
+ * snake_case attributes (`bucket`, `tags`). Attributes without a mapping are
+ * preserved in a reference comment, never dropped.
+ *
+ * Deferred outbound inputs (#998): an attribute whose value the Terraform
+ * source read from a survivor (`vpc_id = aws_vpc.main.id`) is not a fact of
+ * the carved resource — it is a deploy-time input. Those props are emitted as
+ * `params.<name>` references instead of frozen literals, with the state's
+ * resolved value as the declared default (see `carve-emit.ts`'s scaffold).
+ */
+import { AWS_CARVE_TYPES, AWS_LEXICON_IMPORT, awsCarveType, applyAwsMapper, applyAwsFold, unmappedFoldAttrs, } from "../aws-resources.js";
+import { PARAMS_IMPORT, ParamRef, renderObject } from "../emit-source.js";
+/**
+ * TF "sub-resource" types that inline into a parent resource rather than
+ * standing alone (TF splits config CloudFormation keeps in one resource).
+ * A sub-resource that shares its parent's name is folded into the parent's
+ * carve set: it is not ranked on its own, and its edge to the parent does not
+ * count as inbound boundary work — inlining it is free.
+ */
+const AWS_FOLDS_INTO = {
+    aws_s3_bucket_versioning: "aws_s3_bucket",
+    aws_s3_bucket_acl: "aws_s3_bucket",
+    aws_s3_bucket_policy: "aws_s3_bucket",
+    aws_s3_bucket_public_access_block: "aws_s3_bucket",
+    aws_s3_bucket_server_side_encryption_configuration: "aws_s3_bucket",
+    aws_s3_bucket_lifecycle_configuration: "aws_s3_bucket",
+    aws_s3_bucket_website_configuration: "aws_s3_bucket",
+    aws_s3_bucket_cors_configuration: "aws_s3_bucket",
+    aws_s3_bucket_logging: "aws_s3_bucket",
+    aws_s3_bucket_ownership_controls: "aws_s3_bucket",
+    aws_s3_bucket_notification: "aws_s3_bucket",
+    aws_s3_bucket_accelerate_configuration: "aws_s3_bucket",
+    aws_s3_bucket_request_payment_configuration: "aws_s3_bucket",
+    aws_s3_bucket_intelligent_tiering_configuration: "aws_s3_bucket",
+    aws_ecr_lifecycle_policy: "aws_ecr_repository",
+    aws_ecr_repository_policy: "aws_ecr_repository",
+};
+const AWS_TIERS = Object.fromEntries(AWS_CARVE_TYPES.map((t) => [t.tfType, { tier: t.tier, mapsTo: t.nativeType }]));
+const AWS_IDENTITY_ATTRS = Object.fromEntries(AWS_CARVE_TYPES.filter((t) => t.identityAttr).map((t) => [t.tfType, t.identityAttr]));
+/**
+ * Render chant source for a state-adopted resource. Emits the native
+ * constructor with mapped properties, plus a reference comment listing the
+ * Terraform attributes that were not mapped so nothing is silently dropped.
+ *
+ * A mapped attribute named by a `DeferredParam` renders as a `params.<name>`
+ * reference (a real chant build parameter) instead of the state literal —
+ * the value came from a survivor, so it stays overridable per build.
+ *
+ * `folded` carries the carve set's sub-resources (`aws_s3_bucket_versioning`
+ * and friends), read from the same state file. Their mappable attributes join
+ * the parent's props (#1637) — a fold that only announced itself and left the
+ * emitted resource without the versioning or public-access block the Terraform
+ * declared was a silent loss of configuration. A sub-resource's setting wins
+ * over the parent's own legacy in-state block: it is the one the config
+ * actually declares.
+ */
+function adoptAwsFromState(resource, params, folded) {
+    const entry = awsCarveType(resource.type);
+    if (!entry)
+        return null;
+    const { props, mappedKeys } = applyAwsMapper(entry, resource.attributes);
+    const contributions = [];
+    const foldedUnmapped = {};
+    for (const sub of folded) {
+        const address = `${sub.type}.${sub.name}`;
+        const fold = applyAwsFold(sub.type, sub.attributes);
+        // No fold mapping for this sub-resource type: it still carves with the
+        // parent, so report its attributes rather than dropping them on the floor.
+        const rest = fold ? fold.unmapped : unmappedFoldAttrs(sub.attributes);
+        if (fold)
+            Object.assign(props, fold.props);
+        if (Object.keys(rest).length)
+            foldedUnmapped[address] = rest;
+        contributions.push({ address, props: Object.keys(fold?.props ?? {}) });
+    }
+    // Substitute deferred inputs: only plain (untransformed) field mappings can
+    // carry a parameter reference — a transform ran against the literal at emit
+    // time and cannot re-run at build. Everything else keeps the state literal.
+    const parameterized = [];
+    for (const param of params) {
+        const spec = entry.fields[param.tfAttr];
+        if (typeof spec !== "string" || !(spec in props))
+            continue;
+        const type = typeof param.default === "number" ? "number" : typeof param.default === "boolean" ? "boolean" : "string";
+        props[spec] = new ParamRef(param.name, type);
+        parameterized.push(param.name);
+    }
+    const unmapped = {};
+    for (const [k, v] of Object.entries(resource.attributes)) {
+        if (!mappedKeys.includes(k))
+            unmapped[k] = v;
+    }
+    // A folded sub-resource's leftovers are keyed by its address, so the comment
+    // says which block a stray attribute came from.
+    for (const [address, attrs] of Object.entries(foldedUnmapped))
+        unmapped[address] = attrs;
+    const L = [];
+    L.push(`// Adopted from Terraform state: ${resource.type}.${resource.name} -> ${entry.nativeType}`);
+    L.push(`// Properties mapped from Terraform attributes (CloudFormation PascalCase).`);
+    for (const c of contributions) {
+        const into = c.props.length ? c.props.join(", ") : "nothing mappable — see the reference comment below";
+        L.push(`// Folded in ${c.address} -> ${into}`);
+    }
+    L.push(`import { ${entry.ctor} } from "${AWS_LEXICON_IMPORT}";`);
+    if (parameterized.length) {
+        L.push(`// Deferred deploy-time input(s) — declared in chant.config.ts's buildParams.`);
+        L.push(`import { params } from "${PARAMS_IMPORT}";`);
+    }
+    L.push("");
+    L.push(`export const ${resource.name} = new ${entry.ctor}(${renderObject(props, 2)});`);
+    if (Object.keys(unmapped).length) {
+        L.push("");
+        L.push("/* Unmapped Terraform attributes (reconcile to native props before building):");
+        L.push(JSON.stringify(unmapped, null, 2));
+        L.push("*/");
+    }
+    return {
+        fileName: `${resource.name}.ts`,
+        content: L.join("\n") + "\n",
+        mapped: Object.keys(props).length > 0,
+        nativeType: entry.nativeType,
+        parameterized,
+        folded: contributions,
+    };
+}
+export const awsCarveProvider = {
+    name: "aws",
+    tfTypePrefixes: ["aws_"],
+    lexicon: "aws",
+    tiers: AWS_TIERS,
+    identityAttrs: AWS_IDENTITY_ATTRS,
+    foldsInto: AWS_FOLDS_INTO,
+    // Every ranked AWS type is emittable: advise and emit derive from the one
+    // table, so there is no advise↔emit cliff to fall off.
+    emitTypes: AWS_CARVE_TYPES.map((t) => t.tfType),
+    adopt: adoptAwsFromState,
+    // The live import filters a CloudFormation stack's template, so the selector
+    // is the CFN type the carve table already records.
+    liveSelectorType: (tfType) => awsCarveType(tfType)?.nativeType,
+};