@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/composites/terraform-watch-op.test.ts

@@ -45,7 +45,7 @@ describe("TerraformWatchOp phases (#2087)", () => {
     }
   });
 
-  test("the Plan step reports drift as a search attribute", () => {
+  test("the Plan step reports drift as a run outcome", () => {
     const plan = props({ name: "app-watch", root: "app" }).phases[1].steps[0] as ActivityStep;
     expect(plan.fn).toBe("terraformPlan");
     expect(plan.id).toBe("plan");
@@ -145,40 +145,99 @@ describe("TerraformWatchOp posts the human plan and never the plan JSON (#2087)"
   });
 });
 
-describe("TerraformWatchOp schedule (#2087)", () => {
-  test("omitting `schedule` returns no schedule", () => {
-    const result = TerraformWatchOp({ name: "app-watch", root: "app" });
-    expect(result.schedule).toBeUndefined();
-    expect(Object.prototype.hasOwnProperty.call(result, "schedule")).toBe(false);
+describe("TerraformWatchOp on a live root (#2105)", () => {
+  const live = (over: Partial<Parameters<typeof TerraformWatchOp>[0]> = {}): OpConfig =>
+    props({ name: "estate-watch", root: "estate", live: true, ...over });
+
+  test("the Plan step is choudoufuLivePlan, and Init is unchanged", () => {
+    const op = live();
+    expect(phaseNames(op)).toEqual(["Init", "Plan"]);
+    expect(steps(op).map((s) => s.fn)).toEqual(["terraformInit", "choudoufuLivePlan"]);
   });
 
-  test("a cron returns a Temporal::Schedule beside the Op", () => {
-    const { op, schedule } = TerraformWatchOp({
-      name: "app-watch",
-      root: "app",
-      schedule: "0 6 * * *",
+  test("one live read publishes Drift, Unowned and Adoptable", () => {
+    const plan = live().phases[1].steps[0] as ActivityStep;
+    expect(plan.id).toBe("plan");
+    // `drift` off `-detailed-exitcode`, `unowned`/`adoptable` off the same
+    // run's #788 document: three answers, one estate-wide sweep.
+    expect(plan.outcomeAttribute).toEqual([
+      { name: "Drift", from: "drift" },
+      { name: "Unowned", from: "unowned" },
+      { name: "Adoptable", from: "adoptable" },
+    ]);
+  });
+
+  test("the Op is marked live, and no plan file is named anywhere", () => {
+    const op = live();
+    expect(op.labels).toMatchObject({ TerraformMode: "live" });
+    expect(JSON.stringify(op)).not.toContain("chant.tfplan");
+  });
+
+  test("planFile on a live root is refused at build time, quoting choudoufu", () => {
+    expect(() => live({ planFile: "estate.tfplan" })).toThrow(/planFile is refused on a live root/);
+  });
+
+  test("estate off a live root is refused: there is no live plan to name one for", () => {
+    expect(() => props({ name: "app-watch", root: "app", estate: "prod" })).toThrow(/not on a live root/);
+  });
+
+  test("an explicit estate rides the Plan step", () => {
+    const plan = live({ estate: "prod-networking" }).phases[1].steps[0] as ActivityStep;
+    expect(plan.args?.estate).toBe("prod-networking");
+  });
+
+  test("a stock root is untouched: still terraformPlan, still one Drift attribute", () => {
+    const plan = props({ name: "app-watch", root: "app" }).phases[1].steps[0] as ActivityStep;
+    expect(plan.fn).toBe("terraformPlan");
+    expect(plan.outcomeAttribute).toEqual({ name: "Drift", from: "changed" });
+  });
+
+  for (const mode of ["issue", "pull-request"] as const) {
+    test(`${mode}: the body is the plan text plus the adoption ledger, as one field`, () => {
+      const op = live({ findingMode: mode });
+      expect(phaseNames(op)).toEqual(["Init", "Plan", "Report"]);
+      const report = op.phases[2].steps[0] as ActivityStep;
+      expect(report.fn).toBe("reconcilePr");
+      expect(isStepOutputRef(report.args?.body)).toBe(true);
+      expect(report.args?.body).toMatchObject({ step: "plan", path: "finding" });
     });
-    expect(schedule).toBeDefined();
-    expect(schedule!.entityType).toBe("Temporal::Schedule");
-    expect(schedule!.lexicon).toBe("temporal");
-    expect((schedule as unknown as { props: Record<string, unknown> }).props).toEqual({
-      scheduleId: "app-watch-schedule",
-      spec: { cronExpressions: ["0 6 * * *"] },
-      action: { workflowType: "appWatchWorkflow", taskQueue: "app-watch" },
+
+    test(`${mode}: no reference to the live-plan document reaches the body`, () => {
+      // On a live root the JSON is choudoufu's bound/omissions/unowned
+      // document: live identities and tag values for every resource the
+      // estate touched. Same rule as the stock plan's JSON, same test.
+      const op = live({ findingMode: mode });
+      const report = op.phases[2].steps[0] as ActivityStep;
+      const paths = collectStepOutputRefs(report.args).map((r) => r.path);
+      expect(paths).toEqual(["finding"]);
+      expect(paths).not.toContain("json");
+      expect(JSON.stringify(report.args)).not.toContain("json");
     });
-    expect((op as unknown as { props: OpConfig }).props.taskQueue).toBe("app-watch");
+  }
+
+  test("the whole live Op references exactly one field of the plan", () => {
+    const op = live({ findingMode: "issue" });
+    const refs = op.phases.flatMap((p) => p.steps.filter(isActivity)).flatMap((s) => collectStepOutputRefs(s.args));
+    expect(refs).toHaveLength(1);
+    expect(refs[0]).toMatchObject({ step: "plan", path: "finding" });
+  });
+});
+
+describe("TerraformWatchOp schedule (#2087, #2120)", () => {
+  test("omitting `schedule` leaves the Op with no cadence", () => {
+    const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
+    expect((op as unknown as { props: OpConfig }).props).not.toHaveProperty("schedule");
   });
 
-  test("an explicit taskQueue reaches both the Op and the schedule action", () => {
-    const { op, schedule } = TerraformWatchOp({
+  test("a cron lands on the Op itself", () => {
+    const { op } = TerraformWatchOp({
       name: "app-watch",
       root: "app",
       schedule: "0 6 * * *",
-      taskQueue: "infra",
     });
-    expect((op as unknown as { props: OpConfig }).props.taskQueue).toBe("infra");
-    expect(
-      ((schedule as unknown as { props: { action: { taskQueue: string } } }).props.action).taskQueue,
-    ).toBe("infra");
+    expect((op as unknown as { props: OpConfig }).props.schedule).toEqual({
+      cron: "0 6 * * *",
+      overlap: "skip",
+    });
   });
 });

package/src/composites/terraform-watch-op.ts

@@ -7,7 +7,7 @@
  * 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 `Drift` search attribute.
+ * the Op as the run's `Drift` outcome.
  *
  * Phases: Init, Plan, and (for a finding mode that opens something) Report.
  *
@@ -23,37 +23,55 @@
  * 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` and `pull-request` call the temporal lexicon's `reconcilePr`
- * activity, the one place in chant that shells to `gh issue create` /
- * `gh pr create`, rather than growing a second copy of those calls here.
+ * `issue` and `pull-request` call core's `reconcilePr` activity, the one place
+ * in chant that shells to `gh issue create` / `gh pr create`, 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 until
- * then `findingMode: "issue"` is the mode with an end-to-end answer and
- * `"pull-request"` opens a PR whose body is the plan.
+ * 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. 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 makes this a `{ op, schedule }` pair, the shape
- * `lexicons/temporal/src/composites/workflow-audit-op.ts` and
- * `reconcile-op.ts` return. The schedule resource is `Temporal::Schedule`,
- * built here through core's own `createResource` rather than imported from
- * `@intentius/chant-lexicon-temporal`: no lexicon in this repo imports
- * another lexicon's package at runtime, and a static import would mean a
- * project that installs terraform and runs `chant run` on the local executor
- * could not load `@intentius/chant-lexicon-terraform` at all without also
- * installing temporal. The declarable is the same one temporal's
- * `TemporalSchedule` produces (`createResource("Temporal::Schedule",
- * "temporal", {})`, `lexicons/temporal/src/resources.ts`), so temporal's
- * serializer renders it unchanged when a project has both.
- *
- * A project with no Temporal at all runs the same Op on a CI cron instead:
- * `generateOpsPipeline` against the github lexicon turns the Op plus its cron
- * into a workflow. `examples/scheduled-watch/` is that recipe.
+ * 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
@@ -63,20 +81,30 @@
  * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
  *
  * // nightly, opening an issue when the plan is non-empty
- * export const { op, schedule } = TerraformWatchOp({
+ * 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, OpResource, type ActivityStep } from "@intentius/chant/op";
-import { createResource } from "@intentius/chant/runtime";
-import type { Declarable } from "@intentius/chant/declarable";
-import { DEFAULT_PLAN_FILE } from "../op/activities/terraform";
-import { terraformInit as initStep, terraformPlan as planStep } from "../op/builders";
+import { CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL, DEFAULT_PLAN_FILE } from "../op/activities/terraform";
+import {
+  terraformInit as initStep,
+  terraformPlan as planStep,
+  choudoufuLivePlan as livePlanStep,
+} from "../op/builders";
 
 /**
  * What to do with a non-empty plan. A subset of core's `OpFindingMode`
@@ -85,36 +113,47 @@ import { terraformInit as initStep, terraformPlan as planStep } from "../op/buil
  */
 export type TerraformFindingMode = "report" | "issue" | "pull-request";
 
-/**
- * `Temporal::Schedule`, built without importing the temporal lexicon. See the
- * module doc for why. Identical to `TemporalSchedule` in
- * `lexicons/temporal/src/resources.ts`.
- */
-const ScheduleResource = createResource("Temporal::Schedule", "temporal", {});
-
-/** `app-watch` becomes `appWatchWorkflow`, matching the temporal serializer's naming. */
-function kebabToCamel(s: string): string {
-  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
-}
-
 export interface TerraformWatchOpConfig {
-  /** Op name (kebab-case). Also the default task queue and schedule id base. */
+  /** Op name (kebab-case). */
   name: string;
   /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
   root: string;
   /**
-   * Cron expression. When set, a `Temporal::Schedule` is returned alongside
-   * the Op; omit for one-shot `chant run` on the local executor, or for a CI
-   * cron built by `generateOpsPipeline`.
+   * Cron expression. When set, it lands on the Op as `schedule` — the cadence
+   * `chant operator` ticks on and `generateOpsPipeline` renders as a CI cron.
+   * Omit for one-shot `chant run` on the local executor.
    */
   schedule?: string;
   /**
    * What to do when the plan proposes changes. Default: `"report"`, which
-   * opens nothing. The `Drift` search attribute and the run's own log are
+   * opens nothing. The `Drift` run outcome and the run's own log are
    * the report.
    */
   findingMode?: TerraformFindingMode;
-  /** Plan file the Plan step writes, relative to the root dir. Default: `chant.tfplan`. */
+  /**
+   * Watch a live root (#2105): the root runs `terraform.binary: "choudoufu"`
+   * and declares an estate, so the Plan phase is `choudoufuLivePlan` rather
+   * than `terraformPlan`. See the module doc for what changes.
+   *
+   * Declared here rather than detected, because a composite is built by
+   * `chant build` without reading a root module's `.tf` files. The activities
+   * detect the estate at run time (`op/activities/live-detect.ts`), but by then
+   * the phases are already serialized. Setting this on a stock root fails at
+   * the first step, with choudoufu's own reason.
+   */
+  live?: boolean;
+  /**
+   * The estate to plan against, for a live root whose estate this Op should
+   * name explicitly. Omitted, `choudoufuLivePlan` auto-detects it from the
+   * root's own `live` block or `estate.chdf.hcl` sidecar, which is the usual
+   * case. Refused on a stock root.
+   */
+  estate?: string;
+  /**
+   * Plan file the Plan step writes, relative to the root dir. Default:
+   * `chant.tfplan`. Refused on a live root, where choudoufu takes no plan file
+   * at all.
+   */
   planFile?: string;
   /** `-upgrade` on the Init step: re-resolve provider and module versions. */
   upgrade?: boolean;
@@ -129,27 +168,49 @@ export interface TerraformWatchOpConfig {
   title?: string;
   /** Branch the pull-request mode opens from. Default: `reconcilePr`'s own. */
   branch?: string;
-  /** Override the task queue. Defaults to `name`. */
-  taskQueue?: string;
 }
 
 export interface TerraformWatchOpResources {
-  /** Op resource. Generates the Init/Plan/[Report] workflow. */
+  /** Op resource. Generates the Init/Plan/[Report] phases. */
   op: InstanceType<typeof OpResource>;
-  /** `Temporal::Schedule`, present only when `schedule` was given. */
-  schedule?: Declarable;
 }
 
 export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatchOpResources {
-  const taskQueue = config.taskQueue ?? config.name;
-  const planFile = config.planFile ?? DEFAULT_PLAN_FILE;
   const findingMode: TerraformFindingMode = config.findingMode ?? "report";
   const where = config.cwd ? { cwd: config.cwd } : {};
 
-  // `id` is what makes `plan.out` legal, and `plan.out.text` is the only
-  // channel by which any part of the plan leaves this Op.
-  const plan = planStep(config.root, { planFile, ...where, id: "plan" });
-  plan.outcomeAttribute = { name: "Drift", from: "changed" };
+  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.",
+    );
+  }
+
+  // `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 } : {}) })]),
@@ -169,7 +230,11 @@ export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatch
         mode: findingMode,
         entries: [],
         title: config.title ?? `Terraform drift in root "${config.root}"`,
-        body: plan.out.text,
+        // 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:
@@ -180,25 +245,17 @@ export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatch
 
   const op = Op({
     name: config.name,
-    overview: `Plan the "${config.root}" terraform root and report drift`,
-    taskQueue,
-    searchAttributes: {
+    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" as const } } : {}),
     phases,
   });
 
-  if (!config.schedule) return { op };
-
-  const schedule = new ScheduleResource({
-    scheduleId: `${config.name}-schedule`,
-    spec: { cronExpressions: [config.schedule] },
-    action: {
-      workflowType: kebabToCamel(config.name) + "Workflow",
-      taskQueue,
-    },
-  });
-
-  return { op, schedule };
+  return { op };
 }

package/src/config.ts

@@ -25,6 +25,20 @@
 import { z } from "zod";
 import type { ChantConfig } from "@intentius/chant/config";
 
+/**
+ * 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"]);
+export type TerraformDeleteMode = z.infer<typeof terraformDeleteModeSchema>;
+
 /**
  * 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.
@@ -43,14 +57,29 @@ export const terraformRootSchema = z.strictObject({
   varFiles: z.array(z.string()).optional(),
   /** `-backend-config` key/value pairs handed to `init`. */
   backendConfig: z.record(z.string(), 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. The two are wire-compatible for everything
-   * this lexicon does, so the choice is recorded rather than inferred.
+   * 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`.
    */
-  binary: z.enum(["terraform", "tofu"]).optional(),
+  callModuleType: z.enum(["local", "none", "all"]).optional(),
   /** Named root modules. The name is the entity-key prefix, so keep it stable. */
   roots: z.record(z.string(), terraformRootSchema),
 });