@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

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/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));