@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/composites/terraform-watch-op.js

@@ -0,0 +1,219 @@
+/**
+ * TerraformWatchOp composite (#2087): drift reporting for one root module,
+ * on a schedule.
+ *
+ * The observe position on the lifecycle dial. `TerraformApplyOp` next door
+ * changes the estate; this one never does: it inits, plans, and reports what
+ * the plan found. `terraform plan -detailed-exitcode` is the whole mechanism.
+ * Exit 0 is "the world matches the configuration", exit 2 is drift, and
+ * `terraformPlan` turns that into the boolean `changed`, which rides out of
+ * the Op as the run's `Drift` outcome.
+ *
+ * Phases: Init, Plan, and (for a finding mode that opens something) Report.
+ *
+ * ## Only the human plan is ever posted
+ *
+ * `terraformPlan` returns two renders of the same plan: `json`, from
+ * `terraform show -json`, and `text`, from `terraform show -no-color`. The
+ * JSON one carries every resource attribute value the plan touches, including
+ * provider credentials that no `sensitive` marking covers, because
+ * `sensitive_values` describes the configuration's own declarations rather
+ * than everything a provider puts in a plan. So the issue and pull-request
+ * modes reference `plan.out.text` and nothing else. There is no option to
+ * post the JSON, and `terraform-watch-op.test.ts` asserts no reference to it
+ * reaches the finding step.
+ *
+ * The same rule holds on a live root, where the JSON is choudoufu's own
+ * bound/omissions/unowned document rather than a plan representation, and
+ * carries live identities and tag values for every resource the estate
+ * touched. `choudoufuLivePlan` composes the plan text and the adoption ledger
+ * into one `finding` string for exactly this reason: the body is one
+ * reference to one text field, so there is no arrangement of the args in
+ * which the document reaches a body.
+ *
+ * ## A live root reports three things, not one (#2105)
+ *
+ * `live: true` swaps the Plan step for `choudoufuLivePlan`. On a choudoufu
+ * root ownership is a pair of tags on the resource rather than an entry in a
+ * state file, so a plan against the live system can answer three questions
+ * where a stock plan answers one: whether the estate drifted (the
+ * `-detailed-exitcode` exit, `Drift` as before), how many live resources sit
+ * at a declared identity carrying no marker (`Unowned`), and how many of those
+ * an exact content match makes claimable (`Adoptable`). All three come off a
+ * single live read, published as three run outcomes from the one step.
+ *
+ * The finding modes then carry the adoption ledger under the plan text: one
+ * line per adoptable match with its address, its live identity and the
+ * `tofu-estate`/`tofu-address` values that claim it, in the row form
+ * `live-plan -adoption-only` prints, followed by any contested address. That
+ * is a report, not an action. `TerraformAdoptOp` next door is what writes the
+ * markers, and it gates first.
+ *
+ * ## Findings reuse `reconcilePr`
+ *
+ * `issue`, `comment` and `pull-request` call core's `reconcilePr` activity,
+ * the one place in chant that shells to `gh`, rather than growing a second
+ * copy of those calls here.
+ * That activity built its own change-set summary and had no way to be handed
+ * one, so #2087 added a single field to it (`ReconcilePrArgs.body`), which is
+ * what carries the `-no-color` plan through. Note that the pull-request mode
+ * of `reconcilePr` regenerates chant TypeScript via `chant import`; a
+ * terraform-native regeneration of HCL from live state is #2089, so
+ * `findingMode: "issue"` is the mode with an end-to-end answer and
+ * `"pull-request"` opens a PR whose body is the plan. `"comment"` (#2231) is
+ * the mode for the plan-on-pull-request shape: the plan is posted onto the
+ * pull request that triggered the run and re-edited there on the next push,
+ * which is where a reviewer is already looking. It needs that trigger; a run
+ * without one fails the Report step by name rather than posting elsewhere. On a live root #2089's
+ * question has a different answer rather than a pending one, and it is not
+ * regeneration: see `TerraformAdoptOp`.
+ *
+ * ## The schedule
+ *
+ * A cron lands on the Op itself as `schedule` (#2120), the same field
+ * `WatchOp` and `ConvergeOp` set. It is runtime-neutral data: `chant
+ * operator` reads it as this Op's tick cadence, `generateOpsPipeline` against
+ * the github lexicon renders it as a CI cron, and a hosting lexicon hands it
+ * to its own scheduler. The one-shot `chant run app-watch` path ignores it.
+ * `examples/scheduled-watch/` is the CI recipe.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformWatchOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * // one-shot, local executor: chant run app-watch
+ * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
+ *
+ * // the plan as a sticky comment on the pull request that triggered the run
+ * export const { op } = TerraformWatchOp({
+ *   name: "app-plan",
+ *   root: "app",
+ *   findingMode: "comment",
+ * });
+ *
+ * // nightly, opening an issue when the plan is non-empty
+ * export const { op } = TerraformWatchOp({
+ *   name: "app-watch",
+ *   root: "app",
+ *   schedule: "0 6 * * *",
+ *   findingMode: "issue",
+ * });
+ *
+ * // a choudoufu estate: drift, unowned and adoptable, with the ledger in the issue
+ * export const { op } = TerraformWatchOp({
+ *   name: "estate-watch",
+ *   root: "estate",
+ *   live: true,
+ *   findingMode: "issue",
+ * });
+ * ```
+ */
+import { Op, phase } from "@intentius/chant/op";
+import { resolveRootModeSync } from "../op/resolve-root-mode.js";
+import { CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL, DEFAULT_PLAN_FILE } from "../op/activities/terraform.js";
+import { terraformInit as initStep, terraformPlan as planStep, choudoufuLivePlan as livePlanStep, } from "../op/builders.js";
+export function TerraformWatchOp(config) {
+    const findingMode = config.findingMode ?? "report";
+    const where = config.cwd ? { cwd: config.cwd } : {};
+    if (config.live && config.planFile !== undefined) {
+        throw new Error(`TerraformWatchOp "${config.name}": planFile is refused on a live root. choudoufu: ` +
+            `"${CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL}". A live plan writes no saved plan, so there is no file to name; ` +
+            "drop planFile, or drop live if this root runs stock.");
+    }
+    if (!config.live && config.estate !== undefined) {
+        throw new Error(`TerraformWatchOp "${config.name}": estate names the estate a live plan looks for markers of, and ` +
+            "this Op is not on a live root. Set live: true, or drop estate.");
+    }
+    // The `live` flag against the root it names. Best-effort and synchronous:
+    // `resolveRootModeSync` reads a `chant.config.json` only and returns
+    // undefined for anything else, so a `chant.config.ts` project reaches
+    // neither branch and TF028 is what reports the mismatch there. Where the
+    // mode does resolve, refusing at build time names the Op, which a
+    // post-synth diagnostic does too but a run-time failure at the first step
+    // does not.
+    const resolvedMode = resolveRootModeSync(config.root, config.cwd)?.mode;
+    if (resolvedMode === "live" && !config.live) {
+        throw new Error(`TerraformWatchOp "${config.name}": root "${config.root}" runs choudoufu with a declared estate, ` +
+            "but this Op watches it in stock mode. A stock plan reports drift alone and stays quiet about " +
+            "every unowned and adoptable resource in the estate. Set live: true.");
+    }
+    if (resolvedMode === "state" && config.live) {
+        throw new Error(`TerraformWatchOp "${config.name}": live: true, but root "${config.root}" declares no estate (or ` +
+            "terraform.binary is not \"choudoufu\"), so there is no live system to plan against. Drop " +
+            "live, or declare the root's estate.");
+    }
+    // `id` is what makes `plan.out` legal, and one field of `plan.out` is the
+    // only channel by which any part of the plan leaves this Op.
+    //
+    // A live root reads the live system instead of a state file, so the three
+    // things a watch reports come off one `choudoufuLivePlan`: `drift` from
+    // `-detailed-exitcode`, and `unowned`/`adoptable` from the `-json` document
+    // the same run wrote. Three attributes, one live read: see
+    // `ActivityStep.outcomeAttribute`'s array form (#2105).
+    const plan = config.live
+        ? livePlanStep(config.root, { ...where, ...(config.estate ? { estate: config.estate } : {}), id: "plan" })
+        : planStep(config.root, { planFile: config.planFile ?? DEFAULT_PLAN_FILE, ...where, id: "plan" });
+    plan.outcomeAttribute = config.live
+        ? [
+            { name: "Drift", from: "drift" },
+            { name: "Unowned", from: "unowned" },
+            { name: "Adoptable", from: "adoptable" },
+        ]
+        : { name: "Drift", from: "changed" };
+    const phases = [
+        phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
+        phase("Plan", [plan]),
+    ];
+    if (findingMode !== "report") {
+        // `env` is `reconcilePr`'s name for the thing being reconciled; for
+        // terraform that is the root, which with its workspace is the deployment
+        // target. `entries: []` and `body` together mean the activity opens what
+        // it is given rather than running `chant lifecycle plan` to find out.
+        //
+        // `op` is what keeps the sticky issue this Op's own (#2319). The root
+        // alone does not: a stock drift watch and a `live: true` watch over one
+        // root is the pairing this composite is built for, and before #2319 both
+        // resolved to one env-keyed marker, so each nightly run rewrote the
+        // other's issue title and body. Two Ops in a project do not share a raw
+        // name — it names the Op's output directory — though the marker carries
+        // the slug rather than the raw name, and the slug is not injective; see
+        // `issueMarker` for what that leaves and why it is accepted.
+        const report = {
+            kind: "activity",
+            fn: "reconcilePr",
+            args: {
+                env: config.root,
+                op: config.name,
+                mode: findingMode,
+                entries: [],
+                title: config.title ?? `Terraform drift in root "${config.root}"`,
+                // Stock: the `-no-color` plan. Live: the same plan text with the
+                // adoption ledger under it, which `choudoufuLivePlan` composes into
+                // one `finding` field precisely so that a body is one reference and
+                // the `-json` document has no path into one at all.
+                body: config.live ? plan.out.finding : plan.out.text,
+                ...(config.branch ? { branch: config.branch } : {}),
+            },
+            outcomeAttribute: findingMode === "pull-request"
+                ? { name: "PR", from: "prUrl" }
+                : findingMode === "comment"
+                    ? { name: "Comment", from: "commentUrl" }
+                    : { name: "Issue", from: "issueUrl" },
+        };
+        phases.push(phase("Report", [report]));
+    }
+    const op = Op({
+        name: config.name,
+        overview: config.live
+            ? `Live-plan the "${config.root}" choudoufu estate and report drift, unowned and adoptable resources`
+            : `Plan the "${config.root}" terraform root and report drift`,
+        labels: {
+            Watch: "true",
+            TerraformRoot: config.root,
+            ...(config.live ? { TerraformMode: "live" } : {}),
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        phases,
+    });
+    return { op };
+}

package/dist/config.js

@@ -0,0 +1,118 @@
+/**
+ * The `terraform` namespace in `chant.config.ts` (#1344).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-terraform";  // brings the `terraform` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["terraform"],
+ *   terraform: {
+ *     binary: "tofu",
+ *     roots: {
+ *       app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * One schema, three consumers: core validates the namespace against it at load,
+ * the type below is derived from it, and that derived type is what augments
+ * `ChantConfig`, so an unknown key fails at build time and at compile time for
+ * the same reason, rather than being silently ignored at both.
+ */
+import { z } from "zod";
+/**
+ * chant's cross-lexicon delete-mode vocabulary (`lexicons/k8s/src/op/
+ * activities/kubectl.ts`'s `ApplyDeleteMode`, `packages/core/src/op/
+ * activities/apply.ts`'s `DeleteMode`), read here for a live root and mapped
+ * onto choudoufu's `policy` block (#2106): `"never"` requires the root's
+ * `policy` to set `undeclared_tagged` to `"keep"`, `"untag"` or `"report"`
+ * (TF026 enforces this at build time); `"owned-only"` is choudoufu's own
+ * default verb for that quadrant (`delete`) and needs nothing; `"gated"`
+ * needs nothing beyond `TerraformApplyOp`'s own approval gate. Inert on a
+ * stock root: choudoufu's `policy` block does not exist there.
+ */
+export const terraformDeleteModeSchema = z.enum(["never", "owned-only", "gated"]);
+/**
+ * One Terraform root module chant reads. `dir` is the only required field:
+ * everything else names how the root is invoked rather than what it declares.
+ *
+ * `strictObject`, not `object`. Core applies `.strict()` to the top level of a
+ * declared namespace itself, but nested objects are the lexicon's own to make
+ * strict, and a root entry is exactly where a typo (`varfiles`) would
+ * otherwise land silently.
+ */
+export const terraformRootSchema = z.strictObject({
+    /** Root module directory, relative to the project root (where `chant.config.*` lives). */
+    dir: z.string(),
+    /** Terraform workspace to select for this root. Omitted means `default`. */
+    workspace: z.string().optional(),
+    /** `-var-file` arguments, in order, relative to `dir`. */
+    varFiles: z.array(z.string()).optional(),
+    /** `-backend-config` key/value pairs handed to `init`. */
+    backendConfig: z.record(z.string(), z.string()).optional(),
+    /**
+     * The choudoufu estate this root runs against, for a live root whose HCL
+     * does not declare one of its own (#2479).
+     *
+     * This is the environment dimension. A live root has no backend and no
+     * state file, so nothing about it is positional: dev, staging and
+     * production can be the same directory under different estates, which is
+     * why named roots rather than a directory tree are where environments
+     * belong here.
+     *
+     *     roots: {
+     *       "app-staging": { dir: "./terraform", estate: "app-staging", varFiles: ["staging.tfvars"] },
+     *       "app-prod":    { dir: "./terraform", estate: "app-prod",    varFiles: ["prod.tfvars"] },
+     *     }
+     *
+     * How inputs vary across those environments is `varFiles`, which is
+     * already per-root and ordered - the question a directory tree answers
+     * with HCL inheritance, answered here by a map entry.
+     *
+     * Refused (TF028) when the root's own HCL declares an estate in a `live`
+     * block or `estate.chdf.hcl` sidecar. choudoufu refuses `-estate` beside a
+     * declaration ("This configuration's live block is what names its estate"),
+     * and a value here that the declaration then overrode would be a setting
+     * written down and silently ignored.
+     */
+    estate: z.string().optional(),
+    /** This root's declared delete mode. See {@link terraformDeleteModeSchema}. */
+    delete: terraformDeleteModeSchema.optional(),
+});
+export const terraformConfigSchema = z.strictObject({
+    /**
+     * Which CLI drives the roots. `terraform` and `tofu` are wire-compatible
+     * for everything this lexicon does, so the choice is recorded rather than
+     * inferred. `choudoufu` (#2103) is an OpenTofu fork: a root running it also
+     * needs a declared estate (a `live` block or an `estate.chdf.hcl` sidecar,
+     * seen by the shared HCL parse) before it counts as live. Declaring the
+     * binary alone runs the root stock, exactly as `terraform`/`tofu` do.
+     */
+    binary: z.enum(["terraform", "tofu", "choudoufu"]).optional(),
+    /**
+     * How far a root's parse follows its `module` calls (#2112), spelled the
+     * way tflint spells it. `local` (the default) reads modules sourced from a
+     * relative path, so TF014, TF015 and TF020 see inside them; `none` reads
+     * only each root's own directory; `all` is reserved for fetching registry
+     * and git modules and is refused with a message, since chant fetches
+     * nothing. See `hcl/descend.ts`.
+     */
+    callModuleType: z.enum(["local", "none", "all"]).optional(),
+    /**
+     * The directory a root's local module sources may resolve within (#2874),
+     * absolute or relative to the project root. Unset, it is the project root,
+     * or a root's own directory when its `dir` lies outside the project. A
+     * source that resolves outside it is refused with a warning, as before.
+     *
+     * `chant workspace graph` sets it to the workspace root when it reads a
+     * `terraform` or `choudoufu` member through a reader project of its own,
+     * so a member that calls `../modules/x` keeps its modules. A project
+     * rarely needs it: widening the boundary means reading modules the
+     * project does not own.
+     */
+    moduleRoot: z.string().optional(),
+    /** Named root modules. The name is the entity-key prefix, so keep it stable. */
+    roots: z.record(z.string(), terraformRootSchema),
+});