@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/drift-record.js

@@ -0,0 +1,383 @@
+/**
+ * Drift-record adapters for the terraform family (#4451): a stock root's
+ * state read and plan, and a choudoufu live root's `live-plan -json`,
+ * `live-ls -json` and plan, each into `@intentius/chant/drift-record`
+ * records.
+ *
+ * | source | read | status |
+ * |---|---|---|
+ * | `show -json` over state | `state` | in state: recorded. Declared and not in state: pending |
+ * | `show -json` of a saved plan | `plan` | no `resource_drift` row: in-sync. Drift update: drifted with paths. Drift delete: missing. Create with no prior row: pending. Delete with no drift: undeclared |
+ * | `live-plan -json` | `ownership` | `bound[]`: in-sync, owned by its `source`. `unowned[]` and `adoptable[]`: unclaimed. `ABSENT`: pending. Any other omission: not-observed. `foreign[]`: undeclared, foreign. `controller_held[]`: runtime |
+ * | `live-ls -json` | `ownership` | `declared: false`: undeclared. A gap no live-plan row answers: not-observed |
+ * | live-plan and a plan together | `plan` | bound with a planned update or replace: drifted with paths, the live-plan ownership kept |
+ *
+ * A state read never says in-sync or drifted: `driftRecord` refuses it.
+ *
+ * An omission keeps its token in `evidence.engineCode`, and so does the
+ * `UNOWNED` omission that has no `unowned[]` row: chant reads it as
+ * not-observed (`read-failed`), not as unclaimed, since nothing in the
+ * document says what holds the identity.
+ *
+ * ## Values
+ *
+ * Attribute values come from `./plan-observation.ts`, which already replaced
+ * every value the planner flagged, or that equals a flagged string, with
+ * `(sensitive)`. Here a `(sensitive)` side makes the attribute `sensitive:
+ * true` with neither value, and the record constructor's key-name pass runs
+ * after. `before` is what was expected and `after` what the read found, so
+ * a stock root's drift row reads state then refreshed object, and a live
+ * root's planned update reads declared then live (the plan's after, then
+ * its before).
+ *
+ * ## The import graph
+ *
+ * Like `./change-set.ts`, this imports chant's `drift-record` subpath, the
+ * plan projection and the omission table, never the lexicon's entry point
+ * or `./describe-resources.ts`, so it bundles without TypeScript, node's
+ * process modules or the lint rules (#3421).
+ */
+import { driftRecord, placeDriftRecord, } from "@intentius/chant/drift-record";
+import { LIVE_PLAN_OMISSION_REASONS, readsAsCredentials } from "./live-plan-reasons.js";
+import { blockAddressOf, indexPlan, KNOWN_AFTER_APPLY, SENSITIVE_VALUE } from "./plan-observation.js";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const asArray = (v) => (Array.isArray(v) ? v : []);
+const asString = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const byAddress = (a, b) => byString(a.address, b.address);
+/** True for an address inside a `data` block, which has no drift. */
+function isDataAddress(address) {
+    return /(^|\.)data\./.test(blockAddressOf(address));
+}
+function common(input, engine, read, address) {
+    return {
+        member: input.member,
+        engine,
+        address,
+        ...placeDriftRecord(input, engine, address),
+        observedAt: input.observedAt,
+        read,
+        ...(input.fellBackFrom !== undefined ? { fellBackFrom: input.fellBackFrom } : {}),
+    };
+}
+/** One projected plan change as a drift attribute. `swap` reads the change's after as expected. */
+function attributeOf(change, swap) {
+    const path = change.path;
+    if (change.before === SENSITIVE_VALUE || change.after === SENSITIVE_VALUE)
+        return { path, sensitive: true };
+    const expected = swap ? change.after : change.before;
+    const found = swap ? change.before : change.after;
+    return {
+        path,
+        ...(expected !== null && expected !== undefined && expected !== KNOWN_AFTER_APPLY ? { before: expected } : {}),
+        ...(found !== null && found !== undefined && found !== KNOWN_AFTER_APPLY ? { after: found } : {}),
+    };
+}
+// ── state ──────────────────────────────────────────────────────────────────────
+/** Every managed resource row of a `show -json` state document: address and type. */
+function stateRows(showJson) {
+    const rows = new Map();
+    const walk = (module, prefix) => {
+        const node = isObject(module) ? module : {};
+        for (const entry of asArray(node.resources)) {
+            if (!isObject(entry))
+                continue;
+            const raw = asString(entry.address);
+            if (!raw || entry.mode === "data")
+                continue;
+            const address = prefix && !raw.startsWith(`${prefix}.`) ? `${prefix}.${raw}` : raw;
+            rows.set(address, asString(entry.type) ? { type: asString(entry.type) } : {});
+        }
+        for (const child of asArray(node.child_modules)) {
+            if (isObject(child))
+                walk(child, asString(child.address) ?? prefix);
+        }
+    };
+    const doc = isObject(showJson) ? showJson : {};
+    walk(isObject(doc.values) ? doc.values.root_module : undefined, "");
+    return rows;
+}
+/**
+ * A stock root's records from its state: every managed instance in state is
+ * recorded, every declared block with no instance there is pending, and a
+ * failed read makes every declared block not-observed. Never in-sync or
+ * drifted: state says what the last apply recorded, not what the account
+ * holds.
+ */
+export function terraformStateDriftRecords(input) {
+    const engine = input.engine ?? "terraform";
+    const evidence = { tool: engine, ...(input.version ? { version: input.version } : {}), command: `${engine} show -json` };
+    if (input.failed) {
+        return (input.declared ?? [])
+            .map((address) => driftRecord({
+            ...common(input, engine, "state", address),
+            status: "not-observed",
+            unobserved: { reason: input.failed.reason, ...(input.failed.detail ? { detail: input.failed.detail } : {}) },
+            evidence,
+        }))
+            .sort(byAddress);
+    }
+    const rows = stateRows(input.state);
+    const out = [];
+    for (const [address, row] of rows) {
+        out.push(driftRecord({ ...common(input, engine, "state", address), ...(row.type ? { resourceType: row.type } : {}), status: "recorded", ownership: { verdict: "owned", by: "state" }, evidence }));
+    }
+    const blocks = new Set([...rows.keys()].map(blockAddressOf));
+    for (const address of input.declared ?? []) {
+        if (blocks.has(address) || rows.has(address))
+            continue;
+        out.push(driftRecord({ ...common(input, engine, "state", address), status: "pending", evidence }));
+    }
+    return out.sort(byAddress);
+}
+/**
+ * A stock root's records from a saved plan's `show -json`, one per managed
+ * instance the plan names. A `resource_drift[]` row decides: update is
+ * drifted with its paths (before is state, after the refreshed object),
+ * delete is missing. With no drift row, a create with no prior-state row is
+ * pending, a delete or forget the configuration no longer declares is
+ * undeclared, and anything else is in-sync, since a planned change from
+ * configuration is the change set's to show and not drift.
+ */
+export function terraformPlanDriftRecords(input) {
+    const engine = input.engine ?? "terraform";
+    const doc = isObject(input.plan) ? input.plan : {};
+    const version = input.version ?? asString(doc.terraform_version);
+    const evidence = { tool: engine, ...(version ? { version } : {}), command: `${engine} show -json` };
+    const index = indexPlan(input.plan);
+    const prior = stateRows({ values: isObject(index.priorState) ? index.priorState.values : undefined });
+    const types = new Map();
+    for (const entry of asArray(doc.resource_changes)) {
+        if (isObject(entry) && asString(entry.address) && asString(entry.type))
+            types.set(entry.address, entry.type);
+    }
+    const addresses = [...new Set([...index.changes.keys(), ...index.drift.keys()])].filter((a) => !isDataAddress(a)).sort(byString);
+    return addresses.map((address) => {
+        const type = types.get(address) ?? prior.get(address)?.type;
+        const at = { ...common(input, engine, "plan", address), ...(type ? { resourceType: type } : {}), evidence };
+        const drift = index.drift.get(address);
+        if (drift?.actions.includes("delete"))
+            return driftRecord({ ...at, status: "missing" });
+        if (drift && drift.actions.includes("update")) {
+            const attributes = drift.changes.map((c) => attributeOf(c, false));
+            return driftRecord({ ...at, status: "drifted", ...(attributes.length > 0 ? { attributes } : {}) });
+        }
+        const actions = index.changes.get(address)?.actions ?? [];
+        if (actions.length === 1 && actions[0] === "create" && !prior.has(address))
+            return driftRecord({ ...at, status: "pending" });
+        if (actions.length === 1 && (actions[0] === "delete" || actions[0] === "forget"))
+            return driftRecord({ ...at, status: "undeclared" });
+        return driftRecord({ ...at, status: "in-sync" });
+    });
+}
+// ── choudoufu live-plan ────────────────────────────────────────────────────────
+const BOUND_SOURCES = ["marker", "record", "derived", "cache"];
+/**
+ * A live root's records from `live-plan -json`, read `ownership`, one per
+ * address the document names.
+ *
+ * - `bound[]`: in-sync, `owned` by the row's `source`, the marker on the
+ *   object exactly when the source is `marker`.
+ * - `unowned[]`: unclaimed, `adoptable` when the row carries the adopting
+ *   tag values and `foreign` otherwise, with the estate it does carry. It
+ *   answers before the paired `UNOWNED` omission.
+ * - `adoptable[]`: unclaimed, `adoptable`, the paired omission's token kept.
+ * - an `ABSENT` omission: pending.
+ * - any other omission, `UNOWNED` with no row included: not-observed with
+ *   the reason `LIVE_PLAN_OMISSION_REASONS` gives (`VERIFIED_NOT_IMPORTABLE`
+ *   read-failed, `OUT_OF_SCOPE` filtered), a credentials failure named as
+ *   such.
+ * - `foreign[]`: undeclared, `foreign`, addressed by its identity.
+ * - `controller_held[]`: runtime, `foreign`, held by its controller,
+ *   addressed by the marker's address when it has one and its identity
+ *   otherwise.
+ */
+export function choudoufuLivePlanDriftRecords(input) {
+    const doc = isObject(input.livePlan) ? input.livePlan : {};
+    const version = input.version ?? asString(doc.choudoufu_version);
+    const evidence = (engineCode) => ({
+        tool: "choudoufu",
+        ...(version ? { version } : {}),
+        command: "choudoufu live-plan -json",
+        ...(engineCode ? { engineCode } : {}),
+    });
+    const out = new Map();
+    const put = (address, record) => {
+        if (!out.has(address))
+            out.set(address, driftRecord({ ...common(input, "choudoufu", "ownership", address), ...record }));
+    };
+    const typed = (row) => (asString(row.type) ? { resourceType: asString(row.type) } : {});
+    const omissions = new Map();
+    for (const row of asArray(doc.omissions).filter(isObject)) {
+        const addr = asString(row.addr);
+        if (addr)
+            omissions.set(addr, { reason: asString(row.reason) ?? "", detail: asString(row.detail) ?? "" });
+    }
+    for (const row of asArray(doc.unowned).filter(isObject)) {
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        const heldBy = asString(row.tofu_estate);
+        const adopt = asString(row.adopt_tofu_address);
+        const ownership = adopt || asString(row.adopt_tofu_estate)
+            ? { verdict: "adoptable", markerOnObject: heldBy !== undefined, ...(heldBy ? { by: "marker", ownedBy: heldBy } : {}), ...(adopt ? { adopt } : {}) }
+            : { verdict: "foreign", markerOnObject: heldBy !== undefined, ...(heldBy ? { by: "marker", ownedBy: heldBy } : {}) };
+        put(addr, { ...typed(row), status: "unclaimed", ownership, evidence: evidence(omissions.get(addr)?.reason || "UNOWNED") });
+    }
+    for (const row of asArray(doc.bound).filter(isObject)) {
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        const source = asString(row.source);
+        const by = BOUND_SOURCES.find((s) => s === source);
+        put(addr, { ...typed(row), status: "in-sync", ownership: { verdict: "owned", ...(by ? { by } : {}), markerOnObject: source === "marker" }, evidence: evidence() });
+    }
+    for (const row of asArray(doc.adoptable).filter(isObject)) {
+        const addr = asString(row.addr);
+        if (!addr)
+            continue;
+        const adopt = asString(row.adopt_tofu_address);
+        put(addr, {
+            ...typed(row),
+            status: "unclaimed",
+            ownership: { verdict: "adoptable", markerOnObject: false, ...(adopt ? { adopt } : {}) },
+            evidence: evidence(omissions.get(addr)?.reason),
+        });
+    }
+    for (const [addr, row] of omissions) {
+        const mapped = LIVE_PLAN_OMISSION_REASONS[row.reason] ?? "read-failed";
+        if (mapped === "absent") {
+            put(addr, { status: "pending", evidence: evidence(row.reason) });
+            continue;
+        }
+        const reason = mapped === "read-failed" && readsAsCredentials(row.detail) ? "no-credentials" : mapped;
+        put(addr, {
+            status: "not-observed",
+            unobserved: { reason, ...(row.detail ? { detail: row.detail } : {}) },
+            evidence: evidence(row.reason || undefined),
+        });
+    }
+    for (const row of asArray(doc.foreign).filter(isObject)) {
+        const identity = asString(row.identity);
+        if (!identity)
+            continue;
+        const heldBy = asString(row.tofu_estate);
+        put(identity, {
+            ...typed(row),
+            status: "undeclared",
+            ownership: { verdict: "foreign", markerOnObject: heldBy !== undefined, ...(heldBy ? { by: "marker", ownedBy: heldBy } : {}) },
+            evidence: evidence(),
+        });
+    }
+    for (const row of asArray(doc.controller_held).filter(isObject)) {
+        const address = asString(row.addr) ?? asString(row.identity);
+        if (!address)
+            continue;
+        const heldBy = asString(row.held_by) ?? asString(row.controller);
+        put(address, {
+            ...typed(row),
+            status: "runtime",
+            ownership: { verdict: "foreign", by: "label", ...(heldBy ? { ownedBy: heldBy } : {}) },
+            evidence: evidence(asString(row.controller)),
+        });
+    }
+    return [...out.values()].sort(byAddress);
+}
+/**
+ * A live root's records from `live-ls -json`, read `ownership`. An item with
+ * `declared: false` is undeclared, addressed by its marker's address or else
+ * its identity: `owned` when its marker names this estate, held by the
+ * controller (runtime) when it has `held_by`, `foreign` when it names
+ * another estate. A declared item is live-plan's to answer and is left out.
+ * A gap is not-observed `unsupported-kind` with its rung as the token,
+ * unless `answered` holds its address.
+ */
+export function choudoufuLiveLsDriftRecords(input) {
+    const doc = isObject(input.liveLs) ? input.liveLs : {};
+    const estate = asString(doc.estate);
+    const answered = new Set(input.answered ?? []);
+    const evidence = (engineCode) => ({
+        tool: "choudoufu",
+        ...(input.version ? { version: input.version } : {}),
+        command: "choudoufu live-ls -json",
+        ...(engineCode ? { engineCode } : {}),
+    });
+    const out = new Map();
+    for (const row of asArray(doc.items).filter(isObject)) {
+        if (row.declared !== false)
+            continue;
+        const address = asString(row.address) ?? asString(row.id);
+        if (!address || out.has(address))
+            continue;
+        const tags = isObject(row.tags) ? row.tags : {};
+        const marker = asString(tags["tofu-estate"]);
+        const heldBy = asString(row.held_by);
+        const ownership = heldBy
+            ? { verdict: "foreign", by: "label", ownedBy: heldBy }
+            : marker === undefined
+                ? { verdict: "unknown" }
+                : marker === estate
+                    ? { verdict: "owned", by: "marker", markerOnObject: true }
+                    : { verdict: "foreign", by: "marker", markerOnObject: true, ownedBy: marker };
+        out.set(address, driftRecord({
+            ...common(input, "choudoufu", "ownership", address),
+            ...(asString(row.type) ? { resourceType: asString(row.type) } : {}),
+            status: heldBy ? "runtime" : "undeclared",
+            ownership,
+            evidence: evidence(),
+        }));
+    }
+    for (const row of asArray(doc.gaps).filter(isObject)) {
+        const address = asString(row.address);
+        if (!address || answered.has(address) || out.has(address))
+            continue;
+        out.set(address, driftRecord({
+            ...common(input, "choudoufu", "ownership", address),
+            ...(asString(row.type) ? { resourceType: asString(row.type) } : {}),
+            status: "not-observed",
+            unobserved: { reason: "unsupported-kind", ...(asString(row.detail) ? { detail: asString(row.detail) } : {}) },
+            evidence: evidence(asString(row.rung)),
+        }));
+    }
+    return [...out.values()].sort(byAddress);
+}
+/** live-plan's records, then live-ls's undeclared items and the gaps live-plan did not answer. */
+export function choudoufuLiveDriftRecords(input) {
+    const plan = choudoufuLivePlanDriftRecords(input);
+    if (input.liveLs === undefined)
+        return plan;
+    const answered = new Set(plan.map((r) => r.address));
+    const ls = choudoufuLiveLsDriftRecords({ ...input, liveLs: input.liveLs, answered }).filter((r) => !answered.has(r.address));
+    return [...plan, ...ls].sort(byAddress);
+}
+/**
+ * A live root at the plan depth. Every bound instance is read `plan`: a
+ * planned update or replace is drifted with the plan's paths, since a live
+ * root's prior state is the account itself, and anything else is in-sync.
+ * Its ownership facet is live-plan's. Every other address keeps its
+ * live-plan or live-ls record, read `ownership`, because the plan does not
+ * say who holds it.
+ */
+export function choudoufuLivePlusPlanDriftRecords(input) {
+    const live = choudoufuLiveDriftRecords(input);
+    const index = indexPlan(input.plan);
+    const doc = isObject(input.plan) ? input.plan : {};
+    const version = input.version ?? asString(doc.terraform_version);
+    return live
+        .map((r) => {
+        if (r.read !== "ownership" || r.status !== "in-sync" || r.ownership?.verdict !== "owned")
+            return r;
+        const change = index.changes.get(r.address);
+        const actions = change?.actions ?? [];
+        const moves = actions.includes("update") || (actions.includes("create") && actions.includes("delete"));
+        const attributes = moves ? change.changes.map((c) => attributeOf(c, true)) : [];
+        return driftRecord({
+            ...r,
+            read: "plan",
+            status: moves ? "drifted" : "in-sync",
+            ...(attributes.length > 0 ? { attributes } : {}),
+            evidence: { tool: "choudoufu", ...(version ? { version } : {}), command: "choudoufu live-plan -json, choudoufu show -json" },
+        });
+    })
+        .sort(byAddress);
+}

package/dist/drift-rows.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Drift rows (#4580): one row per object a plan found drifted, by address,
+ * with its action and the object's real name, counted the way a product's
+ * drift report counts. `./drift-record.ts` answers a different question (the
+ * status of each instance the plan names), so it skips create rows, carries
+ * no names and stays as it is.
+ *
+ * A stock root's refresh-only plan reports drift as `resource_drift`, and
+ * every entry there is one row, data blocks and creates included. A full
+ * plan of a root under live resource markers (`live: true`) reads drift from
+ * `resource_changes` instead, seen from the other side: a create there is an
+ * object that no longer exists (delete), a delete one that exists outside
+ * the code (create), a replacement or any other pair of actions an update.
+ * Data blocks, no-op and read entries are not drift.
+ *
+ * These are terragucci's rules (packages/terragucci/src/report/drift.ts:
+ * `liveDrift`, `driftCount`, `driftNames`), so a row count here equals the
+ * count its report gives for the same plan.
+ *
+ * A row carries no attribute values. Its `name` is the first non-empty
+ * string among `name`, `id`, `bucket`, `function_name` and `arn`, read from
+ * the object as found and then as the code has it; a deleted object has no
+ * other place its name survives.
+ *
+ * The module imports nothing, so a product can load it behind a
+ * feature-detect without pulling the lexicon's entry point.
+ */
+/** One drifted object. */
+export interface TerraformDriftRow {
+    /** The resource address, `""` when the plan's entry has none. */
+    address: string;
+    /**
+     * What happened outside the code: `update`, `delete` (the object is gone),
+     * `create` (an object exists that state or code does not hold), or on a
+     * stock root whatever single action the plan's entry names. On a stock
+     * root a delete-and-create pair is `replace`, and any other pair `update`.
+     */
+    action: string;
+    /** The resource type, when the entry names one. */
+    type?: string;
+    /** The object's real name, by the rule in this module's header. */
+    name?: string;
+}
+export interface TerraformPlanDriftRowsOptions {
+    /**
+     * The plan is a full plan of a root under live resource markers, whose
+     * changes are its drift. Default false: a refresh-only plan's
+     * `resource_drift`.
+     */
+    live?: boolean;
+}
+/**
+ * The drift a plan (`show -json`, parsed) found, one row per drifted object
+ * in the plan's order. Its length is the drift count.
+ */
+export declare function terraformPlanDriftRows(plan: unknown, options?: TerraformPlanDriftRowsOptions): TerraformDriftRow[];
+/** How many objects a plan found drifted: `terraformPlanDriftRows(plan, options).length`. */
+export declare function terraformPlanDriftCount(plan: unknown, options?: TerraformPlanDriftRowsOptions): number;
+/** Each drifted object's real name by address, for the rows that have one. */
+export declare function terraformPlanDriftNames(plan: unknown, options?: TerraformPlanDriftRowsOptions): Map<string, string>;
+//# sourceMappingURL=drift-rows.d.ts.map

package/dist/drift-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-rows.d.ts","sourceRoot":"","sources":["../src/drift-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,0BAA0B;AAC1B,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA6DD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,iBAAiB,EAAE,CAGtH;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,MAAM,CAE1G;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAIvH"}

package/dist/drift-rows.js

@@ -0,0 +1,108 @@
+/**
+ * Drift rows (#4580): one row per object a plan found drifted, by address,
+ * with its action and the object's real name, counted the way a product's
+ * drift report counts. `./drift-record.ts` answers a different question (the
+ * status of each instance the plan names), so it skips create rows, carries
+ * no names and stays as it is.
+ *
+ * A stock root's refresh-only plan reports drift as `resource_drift`, and
+ * every entry there is one row, data blocks and creates included. A full
+ * plan of a root under live resource markers (`live: true`) reads drift from
+ * `resource_changes` instead, seen from the other side: a create there is an
+ * object that no longer exists (delete), a delete one that exists outside
+ * the code (create), a replacement or any other pair of actions an update.
+ * Data blocks, no-op and read entries are not drift.
+ *
+ * These are terragucci's rules (packages/terragucci/src/report/drift.ts:
+ * `liveDrift`, `driftCount`, `driftNames`), so a row count here equals the
+ * count its report gives for the same plan.
+ *
+ * A row carries no attribute values. Its `name` is the first non-empty
+ * string among `name`, `id`, `bucket`, `function_name` and `arn`, read from
+ * the object as found and then as the code has it; a deleted object has no
+ * other place its name survives.
+ *
+ * The module imports nothing, so a product can load it behind a
+ * feature-detect without pulling the lexicon's entry point.
+ */
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const FLIP = { create: "delete", delete: "create" };
+const NAME_KEYS = ["name", "id", "bucket", "function_name", "arn"];
+function nameOf(values) {
+    const objects = values.filter(isObject);
+    for (const key of NAME_KEYS) {
+        const v = objects.map((x) => x[key]).find((x) => typeof x === "string" && x !== "");
+        if (typeof v === "string")
+            return v;
+    }
+    return undefined;
+}
+function rowOf(entry, action, values) {
+    const r = isObject(entry) ? entry : {};
+    const name = nameOf(values);
+    return {
+        address: typeof r.address === "string" ? r.address : "",
+        action,
+        ...(typeof r.type === "string" && r.type !== "" ? { type: r.type } : {}),
+        ...(name !== undefined ? { name } : {}),
+    };
+}
+function stockAction(actions) {
+    if (actions.length === 1)
+        return actions[0];
+    if (actions.length === 2 && actions.includes("delete") && actions.includes("create"))
+        return "replace";
+    return "update";
+}
+/** A refresh-only plan's `resource_drift`, one row per entry. */
+function stockRows(doc) {
+    const list = Array.isArray(doc.resource_drift) ? doc.resource_drift : [];
+    return list.map((entry) => {
+        const ch = isObject(entry) && isObject(entry.change) ? entry.change : {};
+        const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+        return rowOf(entry, stockAction(actions), [ch.after, ch.before]);
+    });
+}
+/** A live root's full plan, its changes read as drift. */
+function liveRows(doc) {
+    const list = Array.isArray(doc.resource_changes) ? doc.resource_changes : [];
+    const out = [];
+    for (const entry of list) {
+        if (!isObject(entry) || entry.mode === "data")
+            continue;
+        const ch = isObject(entry.change) ? entry.change : {};
+        const actions = Array.isArray(ch.actions) ? ch.actions.map(String) : [];
+        if (actions.length === 0 || actions.every((a) => a === "no-op" || a === "read"))
+            continue;
+        const action = actions.length === 1 ? (FLIP[actions[0]] ?? actions[0]) : "update";
+        const live = isObject(ch.before) ? ch.before : null;
+        let code = isObject(ch.after) ? ch.after : null;
+        // A value the plan knows only after the apply is not a difference: the live one stands for it.
+        const unknown = isObject(ch.after_unknown) ? ch.after_unknown : {};
+        if (code && live)
+            code = { ...code, ...Object.fromEntries(Object.keys(unknown).filter((k) => unknown[k] === true && k in live).map((k) => [k, live[k]])) };
+        out.push(rowOf(entry, action, [live, code]));
+    }
+    return out;
+}
+/**
+ * The drift a plan (`show -json`, parsed) found, one row per drifted object
+ * in the plan's order. Its length is the drift count.
+ */
+export function terraformPlanDriftRows(plan, options = {}) {
+    if (!isObject(plan))
+        return [];
+    return options.live ? liveRows(plan) : stockRows(plan);
+}
+/** How many objects a plan found drifted: `terraformPlanDriftRows(plan, options).length`. */
+export function terraformPlanDriftCount(plan, options = {}) {
+    return terraformPlanDriftRows(plan, options).length;
+}
+/** Each drifted object's real name by address, for the rows that have one. */
+export function terraformPlanDriftNames(plan, options = {}) {
+    const out = new Map();
+    for (const row of terraformPlanDriftRows(plan, options))
+        if (row.name !== undefined)
+            out.set(row.address, row.name);
+    return out;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OpenTofu, Terraform and choudoufu outcomes mapped onto chant's exit-code
+ * table (#4553, `CHANT_EXIT` in `@intentius/chant/exit-codes`).
+ *
+ * The lexicon never picks the process's exit code itself: for a moved plan it
+ * throws an error core marks as moved (`planMoved: true`, read by
+ * `isPlanMovedError`), and core exits `CHANT_EXIT.moved`. This mapping says
+ * which engine outcome is which row of the table, so the throw sites and the
+ * reference page agree.
+ *
+ * | Engine outcome | Table |
+ * |---|---|
+ * | `plan -detailed-exitcode` 0 or 2 | not an exit: the plan's answer. 2 under a drift check is `drift` |
+ * | any 1 | `failed` |
+ * | choudoufu `apply <planfile>` 3, approval mismatch | `moved` |
+ * | choudoufu `apply <planfile>` 3, plan made against another estate | `failed`: the pipeline handed the wrong file, and no approval fixes that |
+ * | choudoufu `live-wave-apply` 3, set moved | `moved` |
+ * | choudoufu `live-wave-apply` 4 or `live-plan-set` 4, a root failed | `failed` |
+ * | a composed plan that moved | `moved` |
+ * | `live-affected` 2, `live-cone` 2 | planner answers, never a job's exit |
+ */
+import { type ChantExitCode } from "@intentius/chant/exit-codes";
+import { type TerraformApprovalRefusal } from "./op/activities/terraform.js";
+/** The command whose exit status is mapped. */
+export type TerraformExitSource = 
+/** `terraform|tofu|choudoufu plan -detailed-exitcode`; `drift` says a drift check asked for it. */
+{
+    command: "plan";
+    code: number;
+    drift?: boolean;
+}
+/** `choudoufu apply <planfile>` on a live root; `refusal` is `classifyApprovalRefusal`'s answer for its output. */
+ | {
+    command: "apply";
+    code: number;
+    refusal?: TerraformApprovalRefusal;
+}
+/** `choudoufu live-wave-apply`. */
+ | {
+    command: "live-wave-apply";
+    code: number;
+}
+/** `choudoufu live-plan-set`. */
+ | {
+    command: "live-plan-set";
+    code: number;
+};
+/**
+ * The table's code for a terraform, tofu or choudoufu exit status. A plan's
+ * 0 and 2 are both `done` unless a drift check asked, when 2 is `drift`.
+ */
+export declare function terraformExitOf(source: TerraformExitSource): ChantExitCode;
+/** Whether `source` is a plan that moved since its approval: the outcomes the lexicon throws a `planMoved` error for. */
+export declare function terraformPlanMoved(source: TerraformExitSource): boolean;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAqD,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE7H,+CAA+C;AAC/C,MAAM,MAAM,mBAAmB;AAC7B,mGAAmG;AACjG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AACpD,mHAAmH;GACjH;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,wBAAwB,CAAA;CAAE;AACxE,mCAAmC;GACjC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC9C,iCAAiC;GAC/B;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAc1E;AAED,yHAAyH;AACzH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAEvE"}

package/dist/exit-codes.js

@@ -0,0 +1,48 @@
+/**
+ * OpenTofu, Terraform and choudoufu outcomes mapped onto chant's exit-code
+ * table (#4553, `CHANT_EXIT` in `@intentius/chant/exit-codes`).
+ *
+ * The lexicon never picks the process's exit code itself: for a moved plan it
+ * throws an error core marks as moved (`planMoved: true`, read by
+ * `isPlanMovedError`), and core exits `CHANT_EXIT.moved`. This mapping says
+ * which engine outcome is which row of the table, so the throw sites and the
+ * reference page agree.
+ *
+ * | Engine outcome | Table |
+ * |---|---|
+ * | `plan -detailed-exitcode` 0 or 2 | not an exit: the plan's answer. 2 under a drift check is `drift` |
+ * | any 1 | `failed` |
+ * | choudoufu `apply <planfile>` 3, approval mismatch | `moved` |
+ * | choudoufu `apply <planfile>` 3, plan made against another estate | `failed`: the pipeline handed the wrong file, and no approval fixes that |
+ * | choudoufu `live-wave-apply` 3, set moved | `moved` |
+ * | choudoufu `live-wave-apply` 4 or `live-plan-set` 4, a root failed | `failed` |
+ * | a composed plan that moved | `moved` |
+ * | `live-affected` 2, `live-cone` 2 | planner answers, never a job's exit |
+ */
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { CHOUDOUFU_APPROVAL_EXIT_CODE, CHOUDOUFU_WAVE_EXIT } from "./op/activities/terraform.js";
+/**
+ * The table's code for a terraform, tofu or choudoufu exit status. A plan's
+ * 0 and 2 are both `done` unless a drift check asked, when 2 is `drift`.
+ */
+export function terraformExitOf(source) {
+    const { code } = source;
+    if (code === 0)
+        return CHANT_EXIT.done;
+    switch (source.command) {
+        case "plan":
+            if (code === 2)
+                return source.drift ? CHANT_EXIT.drift : CHANT_EXIT.done;
+            return CHANT_EXIT.failed;
+        case "apply":
+            return code === CHOUDOUFU_APPROVAL_EXIT_CODE && source.refusal === "approval-mismatch" ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+        case "live-wave-apply":
+            return code === CHOUDOUFU_WAVE_EXIT.setMoved ? CHANT_EXIT.moved : CHANT_EXIT.failed;
+        case "live-plan-set":
+            return code === 2 ? CHANT_EXIT.done : CHANT_EXIT.failed;
+    }
+}
+/** Whether `source` is a plan that moved since its approval: the outcomes the lexicon throws a `planMoved` error for. */
+export function terraformPlanMoved(source) {
+    return terraformExitOf(source) === CHANT_EXIT.moved;
+}