@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/lock-rows.ts

@@ -0,0 +1,82 @@
+/**
+ * The terraform lexicon's lock grain (#4552) and the rows a choudoufu apply
+ * holds on the resource grain, in terragucci's format (`planRows` in
+ * terragucci's `apply-rows.ts` at 18f6431), unchanged:
+ *
+ * - `estate <estate> <address>` for every resource instance the apply acts
+ *   on (a create, update, delete, replace or forget), or `root <root>
+ *   <address>` when the root has no estate;
+ * - the same for `previous_address` on a moved instance;
+ * - `object <id>` for anything but a create, from the object's id before,
+ *   so two estates that meet on one object meet on its row.
+ *
+ * Data reads and no-ops hold nothing.
+ *
+ * The grain: `resource` for choudoufu, which keeps one record per resource,
+ * writes each conditionally and refuses a plan one of whose changes moved;
+ * `target` (the root, or the Terragrunt unit) for Terraform, tofu and
+ * Terragrunt, whose state is one file the backend's lock keeps whole. Those
+ * three refuse `resource` by name, since nothing in their state is per
+ * resource.
+ */
+import type { ChangeSetPart, ChangeSetPlanner } from "@intentius/chant/change-set";
+import { objectRowKey, sortedLockRows, type LockGrain, type LockRow } from "@intentius/chant/lifecycle/lock-rows";
+
+const CHANGING = new Set(["create", "update", "delete", "forget"]);
+
+/** The scope a root's rows are keyed in: its estate, else its path. */
+function rowScope(root: string, estate: string | undefined): string {
+  return estate ? `estate ${estate}` : `root ${root}`;
+}
+
+/** The rows a plan's changes key, from `show -json`'s `resource_changes` (terragucci's `planRows`). */
+export function terraformLockRows(root: string, estate: string | undefined, plan: unknown): LockRow[] {
+  const scope = rowScope(root, estate);
+  const rows: LockRow[] = [];
+  const changes = (plan as { resource_changes?: unknown[] } | undefined)?.resource_changes ?? [];
+  for (const c of changes as Array<Record<string, any>>) {
+    if (c?.mode === "data" || typeof c?.address !== "string") continue;
+    const actions: string[] = Array.isArray(c.change?.actions) ? c.change.actions : [];
+    if (!actions.some((a) => CHANGING.has(a))) continue;
+    const address = c.address as string;
+    rows.push({ key: `${scope} ${address}`, target: root, address });
+    if (typeof c.previous_address === "string" && c.previous_address !== address) rows.push({ key: `${scope} ${c.previous_address}`, target: root, address });
+    // The live object an update or a delete acts on: two estates that meet on one object meet here.
+    const id = c.change?.before?.id;
+    if (actions.some((a) => a !== "create") && (typeof id === "string" || typeof id === "number") && String(id) !== "") rows.push({ key: objectRowKey(String(id)), target: root, address });
+  }
+  return sortedLockRows(rows);
+}
+
+/**
+ * The rows from a member's change-set part, when the plan document is not
+ * at hand: the same keys, less the previous address of a moved instance,
+ * which the part does not carry. The part's `scope` is the estate.
+ */
+export function terraformLockRowsFromPart(root: string, part: ChangeSetPart): LockRow[] {
+  const scope = rowScope(root, part.member.planner === "choudoufu" ? part.member.scope : undefined);
+  const rows: LockRow[] = [];
+  for (const e of part.entries) {
+    if (e.action === "no-op" || e.action === "read") continue;
+    rows.push({ key: `${scope} ${e.address}`, target: root, address: e.address });
+    if (e.action !== "create" && e.id) rows.push({ key: objectRowKey(e.id), target: root, address: e.address });
+  }
+  return sortedLockRows(rows);
+}
+
+/** Whether a binary's name is Terragrunt's. */
+function isTerragrunt(binary: string | undefined): boolean {
+  return /^terragrunt(\.exe)?$/.test((binary ?? "").split(/[\\/]/).pop() ?? "");
+}
+
+/** The grain a root takes by default: `resource` under choudoufu, `target` under every other binary. */
+export function terraformDefaultLockGrain(planner: ChangeSetPlanner | undefined): LockGrain {
+  return planner === "choudoufu" ? "resource" : "target";
+}
+
+/** Why a root cannot take `grain`, by engine name, or undefined when it can. */
+export function terraformLockGrainRefusal(grain: LockGrain, planner: ChangeSetPlanner | undefined, binary?: string): string | undefined {
+  if (grain !== "resource" || planner === "choudoufu") return undefined;
+  const engine = isTerragrunt(binary) ? "Terragrunt" : planner === "tofu" ? "tofu" : "Terraform";
+  return `${engine} keeps a root's state in one file that its backend's lock keeps whole, so nothing in it is per resource; the resource grain needs choudoufu (ci.lockGrain: target)`;
+}

package/src/lock-timeout.ts

@@ -0,0 +1,34 @@
+/**
+ * State-lock waits for a plan or an apply (#4545): how long `plan` and
+ * `apply` wait for another run's state lock before failing. Taken from
+ * terragucci's waves, where two jobs of one pipeline can reach the same
+ * backend a moment apart and a failed lock fails the wave for nothing.
+ *
+ * A job that already sets `-lock-timeout` through `TF_CLI_ARGS` or
+ * `TF_CLI_ARGS_<command>` keeps its own: the flag is added only when neither
+ * names one. Terragrunt waves pass the same flag after `--`
+ * (`./terragrunt/wave.ts`, `extra`).
+ */
+
+/** How long a plan or an apply waits for a state lock unless the job set a `-lock-timeout` of its own. */
+export const DEFAULT_LOCK_TIMEOUT = "5m";
+
+/** A duration terraform's `-lock-timeout` takes: `0s`, `30s`, `5m`, `1h30m`. */
+const DURATION = /^(\d+(ms|s|m|h))+$/;
+
+/** Whether `value` is a `-lock-timeout` duration. */
+export function isLockTimeout(value: unknown): value is string {
+  return typeof value === "string" && DURATION.test(value);
+}
+
+/**
+ * The `-lock-timeout` flag a `command` takes: `-lock-timeout=<timeout>`, or
+ * nothing when `TF_CLI_ARGS` or `TF_CLI_ARGS_<command>` in `env` already
+ * names one, or `timeout` is `false`. Throws on a duration terraform refuses.
+ */
+export function lockTimeoutArgs(command: "plan" | "apply", timeout: string | false = DEFAULT_LOCK_TIMEOUT, env: Record<string, string | undefined> = process.env): string[] {
+  if (timeout === false) return [];
+  if (!isLockTimeout(timeout)) throw new Error(`lockTimeout "${timeout}" is not a duration terraform takes, such as "5m" or "30s"`);
+  const set = `${env.TF_CLI_ARGS ?? ""} ${env[`TF_CLI_ARGS_${command}`] ?? ""}`;
+  return /(^|\s)-{1,2}lock-timeout[=\s]/.test(set) ? [] : [`-lock-timeout=${timeout}`];
+}

package/src/lsp/completions.test.ts

@@ -104,7 +104,7 @@ describe("LSP completions", () => {
   it("completes root-entry keys inside chant.config.ts's terraform.roots.<name>", () => {
     const content = "export default {\n  terraform: {\n    roots: {\n      app: {\n        ";
     const items = completions(ctx({ content, position: { line: 4, character: 8 } }));
-    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "delete", "dir", "varFiles", "workspace"]);
+    expect(items.map((i) => i.label).sort()).toEqual(["backendConfig", "backendConfigFiles", "delete", "dir", "signalOnly", "varFiles", "workspace"]);
   });
 
   it("completes the terraform namespace's own top-level keys", () => {

package/src/lsp/option-keys.ts

@@ -25,7 +25,9 @@ export const ROOT_ENTRY_KEYS: OptionKey[] = [
   { key: "workspace", detail: "Terraform workspace to select for this root. Omitted means `default`." },
   { key: "varFiles", detail: "`-var-file` arguments, in order, relative to `dir`." },
   { key: "backendConfig", detail: "`-backend-config` key/value pairs handed to `init`." },
+  { key: "backendConfigFiles", detail: "Backend-config files handed to `init` as `-backend-config=<path>`, before the pairs, relative to `dir`." },
   { key: "delete", detail: '"never" | "owned-only" | "gated" — this root\'s delete mode, mapped onto choudoufu\'s policy block on a live root.' },
+  { key: "signalOnly", detail: "`true` when the root is declared only so a change to it brings this project into the change. The build and live reads skip it." },
 ];
 
 /** `TerraformApplyOpConfig`'s keys (`TerraformApplyOp({ <here> })`). */

package/src/module-catalog/index.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "vitest";
+import {
+  MODULE_CATALOG_SOURCE,
+  exactModuleVersion,
+  moduleCompatibility,
+  registryModuleAddress,
+  staticRows,
+} from "./index";
+import { renderStaticTier } from "./refresh-cli";
+import { parseModuleCompat } from "./types";
+import { SOURCE_COMMIT, STATIC_MEASUREMENT } from "./static-tier";
+
+describe("known-module catalog (chant#4560)", () => {
+  test("vendors the static tier only, with its source commit", () => {
+    expect(MODULE_CATALOG_SOURCE.path).toBe("live/module-compat.json");
+    expect(MODULE_CATALOG_SOURCE.commit).toMatch(/^[0-9a-f]{40}$/);
+    expect(staticRows.length).toBeGreaterThan(0);
+    expect(staticRows.every((r) => r.tier === "static")).toBe(true);
+  });
+
+  test("every vendored row passes the refresh check", () => {
+    expect(() =>
+      parseModuleCompat({ schema: 1, static_measurement: STATIC_MEASUREMENT, static: [...staticRows] }),
+    ).not.toThrow();
+  });
+
+  test("the vendored file is what the refresh script writes", () => {
+    const rendered = renderStaticTier(SOURCE_COMMIT, STATIC_MEASUREMENT, staticRows);
+    expect(rendered).toContain(`at commit\n// ${SOURCE_COMMIT}`);
+    expect(rendered).toContain("static tier only");
+  });
+
+  test("refuses a row whose verdict disagrees with its refusals", () => {
+    const row = { ...staticRows[0], verdict: "refused" as const, refusals: [] };
+    expect(() => parseModuleCompat({ schema: 1, static_measurement: STATIC_MEASUREMENT, static: [row] })).toThrow(
+      /refused with 0 refusals/,
+    );
+  });
+
+  test.each([
+    ["terraform-aws-modules/vpc/aws", "terraform-aws-modules/vpc/aws"],
+    ["registry.terraform.io/terraform-aws-modules/vpc/aws", "terraform-aws-modules/vpc/aws"],
+    ["terraform-aws-modules/iam/aws//modules/iam-role", "terraform-aws-modules/iam/aws"],
+    ["./modules/vpc", undefined],
+    ["git::https://example.com/vpc.git?ref=v1", undefined],
+  ])("registryModuleAddress(%s)", (source, want) => {
+    expect(registryModuleAddress(source)).toBe(want);
+  });
+
+  test.each([
+    ["1.4.0", "1.4.0"],
+    ["= 1.4.0", "1.4.0"],
+    ["v1.4.0", "1.4.0"],
+    ["~> 1.4", undefined],
+  ])("exactModuleVersion(%s)", (version, want) => {
+    expect(exactModuleVersion(version)).toBe(want);
+  });
+
+  test("a clear version", () => {
+    expect(moduleCompatibility("terraform-aws-modules/sqs/aws", "5.2.2")).toMatchObject({
+      tier: "static",
+      status: "clear",
+      examples: 1,
+      clearExamples: 1,
+      refusedExamples: 0,
+      refusals: [],
+    });
+  });
+
+  test("a refused version sums sites per refusal ID and lists its examples", () => {
+    const c = moduleCompatibility("terraform-aws-modules/eks/aws", "= 21.29.0")!;
+    expect(c.status).toBe("refused");
+    expect(c.refusedExamples).toBe(c.examples);
+    expect(c.refusals.length).toBeGreaterThan(0);
+    for (const r of c.refusals) {
+      expect(r.sites).toBeGreaterThan(0);
+      expect(r.examples.length).toBeGreaterThan(0);
+      expect(r.docsUrl).toMatch(/LIMITATIONS\.md#/);
+    }
+  });
+
+  test("unknown module and unknown version", () => {
+    expect(moduleCompatibility("cloudposse/label/null", "0.25.0")?.status).toBe("unknown-module");
+    const v = moduleCompatibility("terraform-aws-modules/vpc/aws", "5.0.0")!;
+    expect(v.status).toBe("unknown-version");
+    expect(v.measuredVersions).toContain("6.6.1");
+  });
+
+  test("a range or a non-registry source has no answer", () => {
+    expect(moduleCompatibility("terraform-aws-modules/vpc/aws", "~> 6.0")).toBeUndefined();
+    expect(moduleCompatibility("./modules/vpc", "1.0.0")).toBeUndefined();
+  });
+});

package/src/module-catalog/index.ts

@@ -0,0 +1,159 @@
+/**
+ * The known-module catalog (chant#4560): choudoufu's module compatibility
+ * table (choudoufu#2292, `live/module-compat.json`), vendored in
+ * `./static-tier.ts` and read by TF047 and by terragucci's tip and estate
+ * column (terragucci#1286).
+ *
+ * The catalog holds the static tier only. A static row is one
+ * terraform-aws-modules example at one tag, measured offline by choudoufu's
+ * refusal probe in the onboarded form: `clear` means `choudoufu live-check`
+ * plans it, `refused` lists choudoufu refusal IDs with site counts. The
+ * gauntlet tier (end-to-end runs against an emulator) is a separate table in
+ * choudoufu, has no rows until choudoufu#2291's run, and is never folded into
+ * these numbers: every result here carries `tier: "static"`, and a figure in
+ * it counts static rows only.
+ *
+ * This subpath, `@intentius/chant-lexicon-terraform/module-catalog`, imports
+ * nothing but its own data, so a consumer can load it on its own.
+ */
+import { SOURCE_COMMIT, SOURCE_PATH, STATIC_MEASUREMENT, STATIC_ROWS } from "./static-tier";
+import type { StaticRow } from "./types";
+
+export type { StaticRefusal, StaticRow, StaticMeasurement, StaticSource } from "./types";
+
+/** Where the vendored rows came from. */
+export const MODULE_CATALOG_SOURCE = {
+  repo: "INTENTIUS/choudoufu",
+  path: SOURCE_PATH,
+  commit: SOURCE_COMMIT,
+  /** The static tier's measurement date. */
+  date: STATIC_MEASUREMENT.date,
+  /** The choudoufu commit the static tier was measured at. */
+  measuredAt: STATIC_MEASUREMENT.commit,
+  /** The hashicorp/aws provider version the static tier was measured with. */
+  awsProvider: STATIC_MEASUREMENT.aws_provider,
+} as const;
+
+/** choudoufu's site page that renders both tiers. */
+export const MODULE_COMPATIBILITY_PAGE = "https://intentius.io/choudoufu/aws/compatibility/#modules";
+
+/** The tiers this catalog holds. */
+export type ModuleCatalogTier = "static";
+
+/** Every static row, as vendored. */
+export const staticRows: readonly StaticRow[] = STATIC_ROWS;
+
+/** One refusal ID across the examples of a module version that carry it. */
+export interface ModuleRefusalSummary {
+  id: string;
+  /** Sites summed across the examples that carry it. */
+  sites: number;
+  docsUrl: string;
+  /** Example directories that carry it, sorted. */
+  examples: string[];
+}
+
+/**
+ * What the catalog says about one pinned module version.
+ *
+ * - `unknown-module`: no static row for this module at any version.
+ * - `unknown-version`: rows for the module, none measured at this version
+ *   (`measuredVersions` lists the ones there are).
+ * - `refused`: at least one example at this version is refused.
+ * - `clear`: every measured example at this version is clear.
+ */
+export interface ModuleCompatibility {
+  module: string;
+  /** The pinned version, without a leading `v` or `=`. */
+  version: string;
+  tier: ModuleCatalogTier;
+  status: "unknown-module" | "unknown-version" | "clear" | "refused";
+  /** Static rows measured at this version (an `unmeasured` row is left out). */
+  examples: number;
+  clearExamples: number;
+  refusedExamples: number;
+  /** Refusal IDs at this version, most refused examples first, then by ID. */
+  refusals: ModuleRefusalSummary[];
+  /** Versions the static tier measured for this module, without a leading `v`. */
+  measuredVersions: string[];
+}
+
+/**
+ * The registry address of a module source, without a registry host, a
+ * `//subdir` or a query, lowercased: `registry.terraform.io/terraform-aws-modules/iam/aws//modules/iam-role`
+ * gives `terraform-aws-modules/iam/aws`. Undefined when the source is not a
+ * three-part registry address.
+ */
+export function registryModuleAddress(source: string): string | undefined {
+  let s = source.trim().split("?")[0];
+  const sub = s.indexOf("//");
+  if (sub >= 0) s = s.slice(0, sub);
+  const parts = s.split("/");
+  if (parts.length === 4 && parts[0].includes(".")) parts.shift();
+  if (parts.length !== 3 || parts.some((p) => !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(p))) return undefined;
+  return parts.join("/").toLowerCase();
+}
+
+/** `= 1.4.0`, `v1.4.0` and `1.4.0` all give `1.4.0`; a range gives undefined. */
+export function exactModuleVersion(version: string): string | undefined {
+  const v = version.trim().replace(/^=\s*/, "").replace(/^v/, "");
+  return /^\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(v) ? v : undefined;
+}
+
+const bare = (version: string): string => version.replace(/^v/, "");
+
+function byModule(): Map<string, StaticRow[]> {
+  const out = new Map<string, StaticRow[]>();
+  for (const row of STATIC_ROWS) {
+    const key = row.module.toLowerCase();
+    const list = out.get(key) ?? [];
+    list.push(row);
+    out.set(key, list);
+  }
+  return out;
+}
+
+let index: Map<string, StaticRow[]> | undefined;
+
+/**
+ * The catalog's answer for a module `source` pinned at `version`, or
+ * undefined when the source is not a registry address or the version is not
+ * exact (a range is TF039's finding, and the catalog has no row for one).
+ */
+export function moduleCompatibility(source: string, version: string): ModuleCompatibility | undefined {
+  const module = registryModuleAddress(source);
+  const pinned = exactModuleVersion(version);
+  if (module === undefined || pinned === undefined) return undefined;
+
+  index ??= byModule();
+  const rows = index.get(module) ?? [];
+  const measuredVersions = [...new Set(rows.map((r) => bare(r.version)))].sort();
+  const at = rows.filter((r) => bare(r.version) === pinned && r.verdict !== "unmeasured");
+  const refusedRows = at.filter((r) => r.verdict === "refused");
+
+  const refusals = new Map<string, ModuleRefusalSummary>();
+  for (const row of refusedRows) {
+    for (const r of row.refusals) {
+      const s = refusals.get(r.id) ?? { id: r.id, sites: 0, docsUrl: r.docs_url, examples: [] };
+      s.sites += r.sites;
+      if (!s.examples.includes(row.example)) s.examples.push(row.example);
+      refusals.set(r.id, s);
+    }
+  }
+  for (const s of refusals.values()) s.examples.sort();
+
+  const status: ModuleCompatibility["status"] =
+    rows.length === 0 ? "unknown-module" : at.length === 0 ? "unknown-version" : refusedRows.length > 0 ? "refused" : "clear";
+
+  return {
+    module,
+    version: pinned,
+    tier: "static",
+    status,
+    examples: at.length,
+    clearExamples: at.filter((r) => r.verdict === "clear").length,
+    refusedExamples: refusedRows.length,
+    refusals: [...refusals.values()].sort((a, b) => b.examples.length - a.examples.length || a.id.localeCompare(b.id)),
+    measuredVersions,
+  };
+}

package/src/module-catalog/refresh-cli.ts

@@ -0,0 +1,68 @@
+/**
+ * Refresh the vendored known-module catalog (chant#4560) from choudoufu's
+ * module compatibility table.
+ *
+ *   npm run --prefix lexicons/terraform module-catalog:refresh -- <choudoufu checkout> [ref]
+ *
+ * It reads `live/module-compat.json` at `ref` (default `origin/main`) with
+ * `git show`, so the checkout's working tree is never read and a local edit
+ * cannot leak into the snapshot. The header of the written file names the
+ * source path and the choudoufu commit that last changed the table at that
+ * ref, so a reader can check the snapshot against its source with
+ * `git -C <choudoufu> show <commit>:live/module-compat.json`.
+ *
+ * Only the static tier is vendored. choudoufu keeps the gauntlet tier in a
+ * separate array and the two tiers share no figure (choudoufu#2292 ruling);
+ * the gauntlet array stays out until it has rows (choudoufu#2291), and then
+ * comes in as its own export, never folded into the static rows.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseModuleCompat, type StaticMeasurement, type StaticRow } from "./types";
+
+const SOURCE_PATH = "live/module-compat.json";
+const OUT = join(dirname(fileURLToPath(import.meta.url)), "static-tier.ts");
+
+function git(dir: string, ...args: string[]): string {
+  return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** The TypeScript source of `static-tier.ts` for one snapshot. */
+export function renderStaticTier(commit: string, measurement: StaticMeasurement, rows: readonly StaticRow[]): string {
+  return [
+    "// Code generated by src/module-catalog/refresh-cli.ts. DO NOT EDIT.",
+    "//",
+    `// Vendored from INTENTIUS/choudoufu ${SOURCE_PATH} at commit`,
+    `// ${commit}, static tier only (chant#4560).`,
+    "// The gauntlet tier is a separate array in that file and is not vendored here.",
+    "import type { StaticMeasurement, StaticRow } from \"./types\";",
+    "",
+    `export const SOURCE_PATH = ${JSON.stringify(SOURCE_PATH)};`,
+    `export const SOURCE_COMMIT = ${JSON.stringify(commit)};`,
+    "",
+    `export const STATIC_MEASUREMENT: StaticMeasurement = ${JSON.stringify(measurement, null, 2)};`,
+    "",
+    `export const STATIC_ROWS: readonly StaticRow[] = ${JSON.stringify(rows, null, 2)};`,
+    "",
+  ].join("\n");
+}
+
+function main(argv: string[]): void {
+  const [dir, ref = "origin/main"] = argv;
+  if (!dir) {
+    console.error("usage: refresh-cli.ts <choudoufu checkout> [ref]");
+    process.exit(2);
+  }
+  const commit = git(dir, "log", "-1", "--format=%H", ref, "--", SOURCE_PATH).trim();
+  if (!/^[0-9a-f]{40}$/.test(commit)) {
+    console.error(`${SOURCE_PATH} has no history at ${ref} in ${dir}`);
+    process.exit(1);
+  }
+  const file = parseModuleCompat(JSON.parse(git(dir, "show", `${commit}:${SOURCE_PATH}`)));
+  writeFileSync(OUT, renderStaticTier(commit, file.static_measurement, file.static));
+  console.log(`module catalog: ${file.static.length} static rows from ${SOURCE_PATH} at ${commit}`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main(process.argv.slice(2));