@intentius/chant-lexicon-terraform 0.75.1 → 0.77.0

package/src/op/activities/terraform.test.ts

@@ -23,6 +23,8 @@ import {
   terraformApply,
   terraformShow,
   choudoufuLivePlan,
+  choudoufuLivePlanDocument,
+  choudoufuLiveLs,
   terraformInitCommand,
   terraformPlanCommand,
   terraformApplyCommand,
@@ -36,6 +38,7 @@ import {
   DEFAULT_PLAN_FILE,
   __resetChoudoufuVersionCheckForTests,
 } from "./terraform";
+import { withLiveReadSession } from "@intentius/chant/live-read-session";
 
 // ── The child-process stub ──────────────────────────────────────────────────
 
@@ -601,3 +604,117 @@ describe("every activity forwards the AbortSignal (#2086)", () => {
     });
   }
 });
+
+describe("one command, one read of the account (chant#2498)", () => {
+  const LIVE_PLAN_DOCUMENT = JSON.stringify({ estate: "one-read", bound: [], omissions: [], unowned: [] });
+  const LIVE_LS = JSON.stringify({ estate: "one-read", resources: [] });
+
+  function liveProject(): string {
+    const dir = project({ binary: "choudoufu", roots: { estate: { dir: "./infra" } } });
+    writeFileSync(join(dir, "infra", "estate.chdf.hcl"), 'estate = "one-read"\n');
+    return dir;
+  }
+
+  const runs = (fragment: string): number => execCalls.filter((c) => c.cmd.includes(fragment)).length;
+
+  beforeEach(() => {
+    __resetChoudoufuVersionCheckForTests();
+    replies.push(
+      { match: "choudoufu version", reply: { stdout: "choudoufu v0.15.0 (based on OpenTofu v1.13.0)\non darwin_arm64", stderr: "" } },
+      { match: "live-plan -detailed-exitcode -json", reply: { stdout: LIVE_PLAN_DOCUMENT, stderr: "" } },
+      { match: "-no-color", reply: { stdout: "No changes.\n\nPlan: 0 to add, 0 to change, 0 to destroy.\n", stderr: "" } },
+      { match: "live-ls", reply: { stdout: LIVE_LS, stderr: "" } },
+    );
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+  });
+
+  test("the document alone is one run, with no human render", async () => {
+    const dir = liveProject();
+    const result = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+    expect(result.estate).toBe("one-read");
+    expect(result.drift).toBe(false);
+    expect(result.json).toEqual(JSON.parse(LIVE_PLAN_DOCUMENT));
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(1);
+    expect(runs("-no-color")).toBe(0);
+    expect("text" in result).toBe(false);
+  });
+
+  test("the full activity still makes the two runs, the second for the render", async () => {
+    const dir = liveProject();
+    const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
+    expect(result.text).toContain("No changes.");
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(1);
+    expect(runs("live-plan -detailed-exitcode -no-color")).toBe(1);
+  });
+
+  test("outside a read session, every call reads", async () => {
+    const dir = liveProject();
+    await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+    await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+    await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+    await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(2);
+    expect(runs("live-ls")).toBe(2);
+  });
+
+  test("inside one session, the observation's read and the prediction's read are one live-plan and one live-ls", async () => {
+    const dir = liveProject();
+    await withLiveReadSession(async () => {
+      // What describeResources() does, then what predictBehaviour() does,
+      // then the full activity a finding mode would run on top.
+      const observed = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      const listed = await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+      const predicted = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      const listedAgain = await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+      const rendered = await choudoufuLivePlan({ root: "estate", cwd: dir });
+      expect(predicted.json).toEqual(observed.json);
+      expect(listedAgain.json).toEqual(listed.json);
+      expect(rendered.json).toEqual(observed.json);
+    });
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(1);
+    expect(runs("live-plan -detailed-exitcode -no-color")).toBe(1);
+    expect(runs("live-ls")).toBe(1);
+  });
+
+  test("a different flag is a different read", async () => {
+    const dir = liveProject();
+    await withLiveReadSession(async () => {
+      await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      await choudoufuLivePlanDocument({ root: "estate", cwd: dir, adoptionOnly: true });
+      await choudoufuLiveLs({ root: "estate", cwd: dir, consistent: true });
+      await choudoufuLiveLs({ root: "estate", cwd: dir });
+    });
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(2);
+    expect(runs("live-ls -estate=one-read -json -consistent")).toBe(1);
+    expect(runs("live-ls")).toBe(2);
+    const adoption = execCalls.filter((c) => c.opts.env?.TOFU_LIVE_COLLECT_UNCLAIMED === "1");
+    expect(adoption.length).toBe(1);
+  });
+
+  test("a read that failed is not shared: the next caller reads again", async () => {
+    const dir = liveProject();
+    replies.unshift({ match: "live-plan -detailed-exitcode -json", reply: execError(1, "no credentials") });
+    await withLiveReadSession(async () => {
+      await expect(choudoufuLivePlanDocument({ root: "estate", cwd: dir })).rejects.toThrow("no credentials");
+      replies.shift();
+      const result = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      expect(result.json).toEqual(JSON.parse(LIVE_PLAN_DOCUMENT));
+    });
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(2);
+  });
+
+  test("drift on the shared read is the same drift for every caller", async () => {
+    const dir = liveProject();
+    replies.unshift({
+      match: "live-plan -detailed-exitcode -json",
+      reply: execError(2, "", LIVE_PLAN_DOCUMENT),
+    });
+    await withLiveReadSession(async () => {
+      const first = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      const second = await choudoufuLivePlanDocument({ root: "estate", cwd: dir });
+      expect(first.drift).toBe(true);
+      expect(second.drift).toBe(true);
+    });
+    expect(runs("live-plan -detailed-exitcode -json")).toBe(1);
+  });
+});

package/src/op/activities/terraform.ts

@@ -44,6 +44,7 @@ import { writeFileSync } from "node:fs";
 import { promisify } from "node:util";
 import { resolve, dirname, join } from "node:path";
 import { loadChantConfigUpward } from "@intentius/chant/config";
+import { liveReadKey, memoLiveRead } from "@intentius/chant/live-read-session";
 import { computePlanDigest } from "@intentius/chant/op";
 import type { TerraformConfig, TerraformRootConfig } from "../../config";
 import { detectLiveEstate } from "./live-detect";
@@ -1173,10 +1174,46 @@ export function liveDocumentFrom(stdout: string): string {
   return start === -1 ? stdout : lines.slice(start).join("\n");
 }
 
-export async function choudoufuLivePlan(
+/**
+ * What {@link choudoufuLivePlanDocument} resolves: the document and the facts
+ * around it, and none of the human render. The subset of
+ * {@link ChoudoufuLivePlanResult} a reader of the document needs.
+ */
+export interface ChoudoufuLivePlanDocumentResult extends LivePlanUnownedCounts {
+  /** `true` when `-detailed-exitcode` reported exit 2: the live plan proposes changes. */
+  drift: boolean;
+  /** GitHub issue #788's JSON document, captured whole. */
+  json: unknown;
+  /** Absolute path of the root module directory. */
+  dir: string;
+  /** Where the JSON document was written, relative to `dir`. */
+  documentPath: string;
+  /** The estate this plan ran against. */
+  estate: string;
+}
+
+/**
+ * `live-plan -detailed-exitcode -json` alone: the document, without the
+ * second run that renders the plan for a human (chant #2498).
+ *
+ * Two of {@link choudoufuLivePlan}'s three callers never read `text`:
+ * `describeResources()` indexes the document and `predictBehaviour()` prices
+ * it. Each was paying for the render anyway, and on a drifted estate whose
+ * provider retries a deleted resource the render costs as much as the
+ * document. This is the read they make instead.
+ *
+ * Inside a `withLiveReadSession` scope (core's `live-read-session.ts`) the
+ * run is shared with every identical read in the same command, keyed on
+ * the root, its resolved directory, the binary, the estate, the flags and
+ * the root's environment. The graph command runs in such a scope, so its
+ * observation and its prediction see one `live-plan` between them, and the
+ * graph's statuses and the prediction's figures are statements about the
+ * same read. The document file is still written on every call.
+ */
+export async function choudoufuLivePlanDocument(
   args: ChoudoufuLivePlanArgs & { documentPath?: string },
   signal?: AbortSignal,
-): Promise<ChoudoufuLivePlanResult> {
+): Promise<ChoudoufuLivePlanDocumentResult> {
   const resolved = await resolveRoot(args, signal);
   const { binary, dir } = resolved;
   const estate = resolveEstate(args, resolved, "choudoufuLivePlan");
@@ -1187,8 +1224,6 @@ export async function choudoufuLivePlan(
   // from the declaration itself. See {@link choudoufuLivePlanCommand}.
   const estateFlag: { estate?: string } = resolved.estate === undefined ? { estate } : {};
 
-  let drift: boolean;
-  let jsonStdout: string;
   const planCmd = choudoufuLivePlanCommand({ binary, ...estateFlag, json: true });
   // The document's `adoptable` and `swept` sections are populated only on a
   // run that asked the estate-wide sweep the account-bounded question, which
@@ -1198,30 +1233,47 @@ export async function choudoufuLivePlan(
   // run asks for the same thing. Set only under `adoptionOnly`: the sweep is
   // an account-wide list per admitted type, and an observation read has no use
   // for it.
-  const planEnv = args.adoptionOnly ? { ...env, TOFU_LIVE_COLLECT_UNCLAIMED: "1" } : env;
-  try {
-    const { stdout, stderr } = await run(planCmd, dir, planEnv, signal);
-    report(stdout, stderr);
-    drift = false;
-    jsonStdout = stdout;
-  } catch (err) {
-    const failure = err as ExecFailure;
-    if (typeof failure.code !== "number") throw err;
-    if (failure.code !== 2) {
-      const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
-      throw new Error(
-        `${binary} live-plan failed in ${dir} (exit ${failure.code})${detail ? `\n${detail}` : ""}`,
-      );
+  const adoptionOnly = args.adoptionOnly === true;
+  const planEnv = adoptionOnly ? { ...env, TOFU_LIVE_COLLECT_UNCLAIMED: "1" } : env;
+  const key = liveReadKey("live-plan", { root: args.root, dir, binary, estate, adoptionOnly, env });
+
+  const { drift, jsonStdout } = await memoLiveRead(key, async (): Promise<{ drift: boolean; jsonStdout: string }> => {
+    try {
+      const { stdout, stderr } = await run(planCmd, dir, planEnv, signal);
+      report(stdout, stderr);
+      return { drift: false, jsonStdout: stdout };
+    } catch (err) {
+      const failure = err as ExecFailure;
+      if (typeof failure.code !== "number") throw err;
+      if (failure.code !== 2) {
+        const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
+        throw new Error(
+          `${binary} live-plan failed in ${dir} (exit ${failure.code})${detail ? `\n${detail}` : ""}`,
+        );
+      }
+      report(failure.stdout ?? "", failure.stderr ?? "");
+      return { drift: true, jsonStdout: failure.stdout ?? "" };
     }
-    report(failure.stdout ?? "", failure.stderr ?? "");
-    drift = true;
-    jsonStdout = failure.stdout ?? "";
-  }
+  });
 
   // Belt and braces: v0.14.0 keeps `-json` stdout to the document, so this is
   // the identity on a supported binary. See {@link liveDocumentFrom}.
   const document = liveDocumentFrom(jsonStdout);
   const json: unknown = JSON.parse(document);
+  writeFileSync(join(dir, documentPath), document);
+  return { drift, json, dir, documentPath, estate, ...countLivePlanUnowned(json) };
+}
+
+export async function choudoufuLivePlan(
+  args: ChoudoufuLivePlanArgs & { documentPath?: string },
+  signal?: AbortSignal,
+): Promise<ChoudoufuLivePlanResult> {
+  const { drift, json, dir, documentPath, estate, ...unowned } = await choudoufuLivePlanDocument(args, signal);
+  const resolved = await resolveRoot(args, signal);
+  const { binary } = resolved;
+  const env = terraformEnvironment(resolved.root);
+  const estateFlag: { estate?: string } = resolved.estate === undefined ? { estate } : {};
+
   // #788's document carries no render of the human plan itself
   // (`views.LivePlanDocument` has no such field), so the human text needs a
   // second live read rather than a field on the same response. `-adoption-only`
@@ -1255,8 +1307,6 @@ export async function choudoufuLivePlan(
     text = failure.stdout ?? "";
   }
 
-  writeFileSync(join(dir, documentPath), document);
-
   // An `adoptable[]` row carries its own tagging command in the document
   // (choudoufu #962). An `unowned[]` row does not, and the render is the only
   // place one is printed for it, so the parse still runs on an adoption run
@@ -1279,7 +1329,7 @@ export async function choudoufuLivePlan(
     dir,
     documentPath,
     estate,
-    ...countLivePlanUnowned(json),
+    ...unowned,
     ...parseChoudoufuPlanSummary(text),
   };
 }
@@ -1301,9 +1351,16 @@ export async function choudoufuLiveLs(
   const estate = resolveEstate(args, resolved, "choudoufuLiveLs");
   const env = terraformEnvironment(resolved.root);
 
-  const cmd = choudoufuLiveLsCommand({ binary, estate, ...(args.consistent ? { consistent: true } : {}) });
-  const { stdout, stderr } = await run(cmd, dir, env, signal);
-  report(stdout, stderr);
+  const consistent = args.consistent === true;
+  const cmd = choudoufuLiveLsCommand({ binary, estate, ...(consistent ? { consistent: true } : {}) });
+  // Shared with every identical listing in the same read session, the way
+  // {@link choudoufuLivePlanDocument} shares the document (chant #2498).
+  const key = liveReadKey("live-ls", { root: args.root, dir, binary, estate, consistent, env });
+  const stdout = await memoLiveRead(key, async () => {
+    const result = await run(cmd, dir, env, signal);
+    report(result.stdout, result.stderr);
+    return result.stdout;
+  });
 
   return { json: JSON.parse(stdout), dir, estate };
 }

package/src/plugin.test.ts

@@ -1,6 +1,7 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { behaviourEngineVariables, isBehaviourRefusalReport } from "@intentius/chant/behaviour";
 import { isLexiconPlugin } from "@intentius/chant/lexicon";
 import { validateLexiconConfig } from "@intentius/chant/lexicon-config";
 import type { ChantConfig } from "@intentius/chant/config";
@@ -79,6 +80,27 @@ describe("terraform plugin", () => {
   });
 });
 
+describe("predictBehaviour on the plugin (#2495)", () => {
+  afterEach(() => vi.unstubAllEnvs());
+
+  it("reaches core's engine front with nothing injected, and refuses by name when no engine is set", async () => {
+    for (const name of behaviourEngineVariables("chant")) vi.stubEnv(name, "");
+    const result = await terraformPlugin.predictBehaviour!({
+      environment: "prod",
+      buildOutput: "",
+      from: "declared",
+      traffic: "100 rps, p50",
+      entityNames: ["net/aws_vpc.main"],
+      entities: new Map([
+        ["net/aws_vpc.main", { entityType: "Terraform::Resource", props: { root: "net", address: "aws_vpc.main", body: {} } }],
+      ]),
+      edges: [],
+      edgeCoverage: { verdict: "unknown" },
+    });
+    expect(isBehaviourRefusalReport(result) && result.refusal.cause).toBe("no-engine");
+  });
+});
+
 describe("terraform config schema", () => {
   it("accepts a root with every optional field", () => {
     const parsed = terraformConfigSchema.parse({

package/src/plugin.ts

@@ -135,6 +135,19 @@ export const terraformPlugin: LexiconPlugin = {
     return describeResources(options);
   },
 
+  /**
+   * The prediction, for whichever estate `options.from` names (#2495). The
+   * producer is `predictTerraformBehaviour` and this is its second caller, not
+   * a second producer: the contract's options are read as its own and handed
+   * over, and it runs with the real reads and core's engine front. What that
+   * reading has to put back, for a declared graph and for a live one, is on
+   * `terraformPredictOptionsFrom`.
+   */
+  async predictBehaviour(options) {
+    const { predictTerraformBehaviour, terraformPredictOptionsFrom } = await import("./behaviour");
+    return predictTerraformBehaviour(await terraformPredictOptionsFrom(options));
+  },
+
   /**
    * The kinds a live root can enumerate beyond its declaration (#1278,
    * #2104). Empty on a project with no live root, because `live-ls` is the