@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/components/release-inputs.js

@@ -0,0 +1,57 @@
+/**
+ * The files a release records for a `terraform-apply` step (chant#4542).
+ *
+ * The step names its root by key, so core can't see which files it deploys.
+ * `terraformReleaseInputs` answers core's `releaseInputs` with the set a
+ * pull request's plan treats as the root's change (`rootWatchPaths`): the
+ * root's directory, each local module it reaches, and its var files, plus
+ * its backend-config files. A release cut records them for the component,
+ * and a promote or rollback under the release writes them under
+ * `.chant/release-templates/<digest>/` and sets the step's `dir` to the copy
+ * of the root, so `terraform-apply` plans the release's configuration against
+ * the environment's state.
+ *
+ * A root whose state is a file in its own directory (the `local` backend) is
+ * unbound: a plan run in a copy elsewhere would read no state and propose
+ * creating everything. Such a root rolls back through `chant lifecycle
+ * rollback --to`. A live choudoufu root has no state file and is recorded.
+ */
+import { dirname, relative, resolve } from "node:path";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { rootWatchPaths } from "../changed-roots.js";
+import { liveEstate } from "../compose/hcl.js";
+import { readBackend } from "../state/backend.js";
+const toPosix = (p) => p.split("\\").join("/") || ".";
+/** What a release records for one `terraform-apply` step, relative to the member's directory. Null when the root is not declared. */
+export async function terraformReleaseInputs(input, ctx) {
+    if (typeof input.root !== "string" || input.root === "")
+        return null;
+    const start = resolve(ctx.memberDir, input.cwd ?? ".");
+    const { config, configPath } = await loadChantConfigUpward(start);
+    const projectRoot = configPath ? dirname(configPath) : start;
+    const terraform = config.terraform;
+    const root = terraform?.roots?.[input.root];
+    if (!root)
+        return null;
+    const binary = terraform?.binary;
+    const rootDir = resolve(projectRoot, input.dir ?? root.dir);
+    const live = binary === "choudoufu" && (root.estate !== undefined || liveEstate(rootDir, binary).live);
+    if (!live) {
+        const { backend } = readBackend(rootDir, {
+            ...(root.backendConfig ? { backendConfig: root.backendConfig } : {}),
+            ...(root.backendConfigFiles ? { backendConfigFiles: root.backendConfigFiles } : {}),
+            ...(binary ? { binary } : {}),
+        });
+        if (backend.type === "local") {
+            return {
+                unbound: `root "${input.root}" keeps its state in a local file under ${toPosix(relative(ctx.memberDir, rootDir))}, ` +
+                    "so a plan of a recorded copy would read no state; roll it back with chant lifecycle rollback --to <ref>",
+            };
+        }
+    }
+    const fromMember = (abs) => toPosix(relative(ctx.memberDir, abs));
+    const paths = rootWatchPaths(projectRoot, { dir: relative(projectRoot, rootDir) || ".", ...(root.varFiles ? { varFiles: root.varFiles } : {}) }, binary).map((p) => fromMember(resolve(projectRoot, p)));
+    for (const file of root.backendConfigFiles ?? [])
+        paths.push(fromMember(resolve(rootDir, file)));
+    return { field: "dir", dir: fromMember(rootDir), paths: [...new Set(paths)].sort() };
+}

package/dist/components/trace-facts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `terraform-apply`'s engine facts for its span and op-wave run record
+ * (INTENTIUS/chant#4555): the root, the binary that applied it, and whether
+ * it applied the plan the wave decided. Core adds the plan's resource counts
+ * by action, and writes every key under the CI product's prefix
+ * (`terragucci.root`, `terragucci.binary`).
+ */
+import type { CapabilityTraceFacts } from "@intentius/chant/otlp";
+import type { TerraformApplyStepInput, TerraformApplyStepOutput } from "./capability-plugin.js";
+/** `traceFacts` for `terraform-apply` (#4555). `binary` is the config's `terraform.binary`, `terraform` when it names none. */
+export declare function terraformTraceFacts(input: TerraformApplyStepInput, outcome: {
+    output: TerraformApplyStepOutput;
+} | {
+    error: unknown;
+}, binary: string | undefined): CapabilityTraceFacts;
+//# sourceMappingURL=trace-facts.d.ts.map

package/dist/components/trace-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-facts.d.ts","sourceRoot":"","sources":["../../src/components/trace-facts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,+HAA+H;AAC/H,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE;IAAE,MAAM,EAAE,wBAAwB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,EAClE,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,oBAAoB,CAUtB"}

package/dist/components/trace-facts.js

@@ -0,0 +1,19 @@
+/**
+ * `terraform-apply`'s engine facts for its span and op-wave run record
+ * (INTENTIUS/chant#4555): the root, the binary that applied it, and whether
+ * it applied the plan the wave decided. Core adds the plan's resource counts
+ * by action, and writes every key under the CI product's prefix
+ * (`terragucci.root`, `terragucci.binary`).
+ */
+/** `traceFacts` for `terraform-apply` (#4555). `binary` is the config's `terraform.binary`, `terraform` when it names none. */
+export function terraformTraceFacts(input, outcome, binary) {
+    const bin = (binary ?? "terraform").split(/[\\/]/).pop() || "terraform";
+    return {
+        attributes: {
+            root: input.root,
+            binary: bin,
+            ...("output" in outcome && outcome.output ? { "apply.from_wave_plan": outcome.output.fromWavePlan, "apply.outputs": Object.keys(outcome.output.outputs ?? {}).length } : {}),
+            ...(input.cone ? { "plan.cone": input.cone } : {}),
+        },
+    };
+}

package/dist/cone.d.ts

@@ -0,0 +1,53 @@
+/** The flags choudoufu refuses beside `-cone`, or plans in full with: a plan that carries one gets no `-cone`. */
+export declare const CONE_EXCLUDES: readonly ["-target", "-exclude", "-destroy", "-refresh-only", "-json", "-estate"];
+/** What choudoufu writes beside a saved cone plan, `FILE.cone.json`. */
+export interface ConeRecord {
+    base: string;
+    base_sha: string;
+    targets: string[];
+}
+/** What one root's cone plan did: planned the cone, or planned the whole estate for the guard's reason. */
+export interface PlanCone {
+    /** The revision the plan was asked to measure the change from. */
+    base: string;
+    /** With a cone: its blocks, and the estate's, as choudoufu counted them. Absent when it did not say. */
+    blocks?: number;
+    of?: number;
+    /** With a cone: the record beside the plan file. */
+    record?: ConeRecord;
+    /** The guard planned the whole estate: its kind and why. */
+    fallback?: {
+        kind: string;
+        reason: string;
+    };
+}
+/** Whether `binary` (a name or a path) is choudoufu. */
+export declare const isChoudoufu: (binary: string) => boolean;
+/**
+ * The `-cone` argument a plan takes: `-cone=<base>` for choudoufu with a
+ * base, on a root that takes it (`live`), when none of `args` is a flag in
+ * {@link CONE_EXCLUDES}. Otherwise none, and the plan is full.
+ */
+export declare function coneArgs(binary: string, base: string | undefined, args: readonly string[], cone: boolean): string[];
+/** The path of the cone record beside a plan file. */
+export declare const coneRecordPath: (planFile: string) => string;
+/** The cone record beside `planFile`, or none when there is none or it does not read as one. */
+export declare function readConeRecord(planFile: string): ConeRecord | undefined;
+/**
+ * What a plan run with `-cone=<base>` did, from its output and the record
+ * beside `planFile`. A fallback warning means the whole estate was planned,
+ * even after a cone warning. With no fallback, the record is the cone. With
+ * neither, choudoufu said nothing this reads, and the plan counts as full.
+ */
+export declare function readPlanCone(output: string, planFile: string, base: string): PlanCone;
+/** What a cone plan did, in words: its size, or why it planned the whole estate. */
+export declare function coneText(cone: PlanCone): string;
+/**
+ * A root's plan digest with its cone in it: the plan's own digest, unchanged,
+ * when the plan was full; with a cone, the digest over the plan's digest and
+ * the cone's targets, so an approval of one cone counts for no other. The
+ * digest's kind is terragucci's, so approvals recorded before the move still
+ * name the same digest.
+ */
+export declare function conePlanDigest(planDigest: string, cone: PlanCone | undefined): string;
+//# sourceMappingURL=cone.d.ts.map

package/dist/cone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cone.d.ts","sourceRoot":"","sources":["../src/cone.ts"],"names":[],"mappings":"AA4BA,kHAAkH;AAClH,eAAO,MAAM,aAAa,YAAI,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAE/G,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,2GAA2G;AAC3G,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW,WAAY,MAAM,KAAG,OAA2C,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAInH;AAED,sDAAsD;AACtD,eAAO,MAAM,cAAc,aAAc,MAAM,KAAG,MAAiC,CAAC;AAEpF,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAUvE;AAsBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAUrF;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAK/C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAGrF"}

package/dist/cone.js

@@ -0,0 +1,119 @@
+/**
+ * choudoufu's cone plans (#4545, moved from terragucci's `cone.ts`): `plan
+ * -cone=<base>` plans only the blocks a change touches and every block that
+ * reads them.
+ *
+ * A wave that applies an open pull request plans a live root as the cone of
+ * its change since the pull request's base, as the plan note did. A wave
+ * that applies a merge commit and a drift run plan the whole estate, as do
+ * a root with no `live` block, an estate file (`estate.chdf.hcl`), whose
+ * form choudoufu refuses `-cone` on, and any binary but choudoufu.
+ *
+ * choudoufu's guard can plan the whole estate anyway (no base, a provider,
+ * terraform or live block or the lock file changed, a cone over 30% of the
+ * estate's blocks, and so on). It says why in a warning. A cone plan says
+ * its size in a warning too, and with `-out FILE` writes `FILE.cone.json`:
+ * the cone's base, the commit it named and the addresses it targets.
+ *
+ * The record's targets join the root's plan digest ({@link conePlanDigest}),
+ * so the digest an approval binds names the cone. A wave that plans again
+ * after its approval and finds another cone has another digest, and refuses
+ * as moved. choudoufu's `apply FILE` checks the same record again.
+ *
+ * Pure, apart from reading the record beside a plan file.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+/** The flags choudoufu refuses beside `-cone`, or plans in full with: a plan that carries one gets no `-cone`. */
+export const CONE_EXCLUDES = ["-target", "-exclude", "-destroy", "-refresh-only", "-json", "-estate"];
+/** Whether `binary` (a name or a path) is choudoufu. */
+export const isChoudoufu = (binary) => basename(binary) === "choudoufu";
+/**
+ * The `-cone` argument a plan takes: `-cone=<base>` for choudoufu with a
+ * base, on a root that takes it (`live`), when none of `args` is a flag in
+ * {@link CONE_EXCLUDES}. Otherwise none, and the plan is full.
+ */
+export function coneArgs(binary, base, args, cone) {
+    if (!base || !cone || !isChoudoufu(binary))
+        return [];
+    const excluded = args.some((a) => CONE_EXCLUDES.some((f) => a === f || a.startsWith(`${f}=`)));
+    return excluded ? [] : [`-cone=${base}`];
+}
+/** The path of the cone record beside a plan file. */
+export const coneRecordPath = (planFile) => `${planFile}.cone.json`;
+/** The cone record beside `planFile`, or none when there is none or it does not read as one. */
+export function readConeRecord(planFile) {
+    const path = coneRecordPath(planFile);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const r = JSON.parse(readFileSync(path, "utf-8"));
+        if (!r || typeof r.base !== "string" || !Array.isArray(r.targets) || !r.targets.every((t) => typeof t === "string"))
+            return undefined;
+        return { base: r.base, base_sha: typeof r.base_sha === "string" ? r.base_sha : "", targets: [...r.targets].sort() };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The detail of the last warning with this summary in a plan's output, its
+ * lines joined. The binary prints a warning as `Warning: <summary>`, a blank
+ * line, and the detail up to the next blank line or the plan's summary; a box
+ * drawn around it with colour on is stripped.
+ */
+function warningDetail(text, summary) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n").map((l) => l.replace(/^[\s│╷╵]*/, "").trimEnd());
+    let found;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i] !== `Warning: ${summary}`)
+            continue;
+        let j = i + 1;
+        while (j < lines.length && lines[j] === "")
+            j++;
+        const detail = [];
+        for (; j < lines.length && lines[j] !== "" && !/^(Plan: |No changes\.|Changes to Outputs:)/.test(lines[j]); j++)
+            detail.push(lines[j]);
+        found = detail.join(" ").replace(/\s+/g, " ").trim();
+    }
+    return found;
+}
+/**
+ * What a plan run with `-cone=<base>` did, from its output and the record
+ * beside `planFile`. A fallback warning means the whole estate was planned,
+ * even after a cone warning. With no fallback, the record is the cone. With
+ * neither, choudoufu said nothing this reads, and the plan counts as full.
+ */
+export function readPlanCone(output, planFile, base) {
+    const fell = warningDetail(output, "Cone plan fell back to a full plan");
+    if (fell !== undefined) {
+        const m = /^This plan covers the whole estate \(guard ([^)]*)\): (.*?)\.?$/.exec(fell);
+        return { base, fallback: m ? { kind: m[1], reason: m[2] } : { kind: "unknown", reason: fell } };
+    }
+    const record = readConeRecord(planFile);
+    if (!record)
+        return { base, fallback: { kind: "unknown", reason: "choudoufu wrote no cone record beside the plan" } };
+    const size = /: (\d+) of the estate's (\d+) blocks/.exec(warningDetail(output, "Cone plan") ?? "");
+    return { base, ...(size ? { blocks: Number(size[1]), of: Number(size[2]) } : {}), record };
+}
+/** What a cone plan did, in words: its size, or why it planned the whole estate. */
+export function coneText(cone) {
+    if (cone.fallback)
+        return `the whole estate, since ${cone.fallback.reason} (guard ${cone.fallback.kind})`;
+    const n = cone.record?.targets.length ?? 0;
+    const size = cone.blocks !== undefined && cone.of !== undefined ? `${cone.blocks} of the estate's ${cone.of} blocks` : `${n} target${n === 1 ? "" : "s"}`;
+    return `the cone of the change since ${cone.base}, ${size}`;
+}
+/**
+ * A root's plan digest with its cone in it: the plan's own digest, unchanged,
+ * when the plan was full; with a cone, the digest over the plan's digest and
+ * the cone's targets, so an approval of one cone counts for no other. The
+ * digest's kind is terragucci's, so approvals recorded before the move still
+ * name the same digest.
+ */
+export function conePlanDigest(planDigest, cone) {
+    if (!cone?.record)
+        return planDigest;
+    return computePlanDigest("terragucci-cone-plan", { plan: planDigest, targets: [...cone.record.targets].sort() });
+}

package/dist/cost-hold.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The terraform lexicon's preset for an op wave's cost hold (#4545,
+ * `holds.cost` on the spec): infracost over each root's plan document, the
+ * `show -json` file `terraform-apply`'s plan names as `artifact.planJson`.
+ *
+ * ```ts
+ * const spec = { ..., step: { kind: "terraform-apply", root: "{target}" }, holds: { cost: terraformCostHold({ approveAbove: 100 }) } };
+ * ```
+ *
+ * The shape is core's `OpWaveCostHold`, written out here so the lexicon
+ * builds against a core without it.
+ */
+/** infracost's own command over one plan document. */
+export declare const INFRACOST_ARGV: readonly ["infracost", "breakdown", "--path", "{planJson}", "--format", "json", "--log-level", "error"];
+export interface TerraformCostHold {
+    command: string[];
+    approveAbove: number;
+    format: "infracost";
+    currency?: string;
+}
+/** A cost hold that prices each root with infracost, waiting over `approveAbove` a month. `command` replaces infracost's argv; it must name `{planJson}`. */
+export declare function terraformCostHold(options: {
+    approveAbove: number;
+    currency?: string;
+    command?: string[];
+}): TerraformCostHold;
+//# sourceMappingURL=cost-hold.d.ts.map

package/dist/cost-hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-hold.d.ts","sourceRoot":"","sources":["../src/cost-hold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,sDAAsD;AACtD,eAAO,MAAM,cAAc,YAAI,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,CAAU,CAAC;AAEtI,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6JAA6J;AAC7J,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,iBAAiB,CAI7H"}

package/dist/cost-hold.js

@@ -0,0 +1,21 @@
+/**
+ * The terraform lexicon's preset for an op wave's cost hold (#4545,
+ * `holds.cost` on the spec): infracost over each root's plan document, the
+ * `show -json` file `terraform-apply`'s plan names as `artifact.planJson`.
+ *
+ * ```ts
+ * const spec = { ..., step: { kind: "terraform-apply", root: "{target}" }, holds: { cost: terraformCostHold({ approveAbove: 100 }) } };
+ * ```
+ *
+ * The shape is core's `OpWaveCostHold`, written out here so the lexicon
+ * builds against a core without it.
+ */
+/** infracost's own command over one plan document. */
+export const INFRACOST_ARGV = ["infracost", "breakdown", "--path", "{planJson}", "--format", "json", "--log-level", "error"];
+/** A cost hold that prices each root with infracost, waiting over `approveAbove` a month. `command` replaces infracost's argv; it must name `{planJson}`. */
+export function terraformCostHold(options) {
+    const command = options.command ?? [...INFRACOST_ARGV];
+    if (!command.some((a) => a.includes("{planJson}")))
+        throw new Error("terraformCostHold: the command must name {planJson}, the root's plan document");
+    return { command, approveAbove: options.approveAbove, format: "infracost", ...(options.currency ? { currency: options.currency } : {}) };
+}

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;
+}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { EstateRun, estateVersionFallback, estateOutcomes, readEstateApplyText,
 export { priorStateValues, stateResources, stateOutputs, type StateResourceValues } from "./applied-state.js";
 export { ComposedRun, composedPlanDigest, changesSomething, type ComposedRunOptions, type ComposedRunStage, type StateRunPlan, type StateRunApply, type StateMemberOutcome, type ComposedStateWrite, type ComposeHook, type ComposeHookMoment, } from "./compose/run.js";
 export { terraformPlanShape, type TerraformPlanShapeOptions } from "./plan-shape.js";
+export { terraformLockRows, terraformLockRowsFromPart, terraformDefaultLockGrain, terraformLockGrainRefusal } from "./lock-rows.js";
 export { compositionFor, compositionIfEnabled, composeOff, composeSet, readOrder, moduleNames, fallbackLine, withPlanFailed, identityKey, DEFAULT_COMPOSE_MAX, COMPOSE_STEP_KIND, type Composition, type CompositionInput, type ComposedRead, type ComposeFallback, type ComposeFallbackKind, type ExpectedBinary, } from "./compose.js";
 export { terraformSerializer } from "./serializer.js";
 export { terraformConfigSchema, terraformRootSchema, type TerraformConfig, type TerraformRootConfig, type TerraformConfigNamespace, } from "./config.js";
@@ -25,4 +26,5 @@ export { TerraformPinRolloutOp } from "./composites/terraform-pin-rollout-op.js"
 export type { TerraformPinRolloutOpConfig, TerraformPinRolloutOpResources } from "./composites/terraform-pin-rollout-op.js";
 export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
 export { predictTerraformBehaviour, terraformBehaviourRequest, terraformPredictOptionsFrom, TERRAFORM_REFERENCE_CATALOG, type TerraformBehaviourDeps, type TerraformBehaviourEntity, type TerraformBehaviourRequest, type TerraformBehaviourRequestOptions, type TerraformLiveRead, type TerraformPredictOptions, } from "./behaviour/index.js";
+export { terraformExitOf, terraformPlanMoved, type TerraformExitSource } from "./exit-codes.js";
 //# sourceMappingURL=index.d.ts.map