@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/pin/edit-ts.ts

@@ -0,0 +1,77 @@
+/**
+ * The pin edit for a root chant generates (#3189): move the pin in the
+ * module declaration of its TypeScript source, not in the `.tf` a build
+ * writes from it.
+ *
+ * A module declaration in TypeScript is an object literal with the same
+ * arguments the HCL block has: a `source` string, and a `version` string
+ * beside a registry source. Any object literal whose `source` is a plain
+ * string naming the module counts, whatever function or constructor receives
+ * it. The TypeScript compiler parses the file, so a `source:` inside a
+ * comment, a template with substitutions, or another string is never a
+ * match, and the edit replaces the string literal's content only. Every other
+ * byte of the file stays as it was.
+ *
+ * It needs the TypeScript compiler, so `./index.ts` (the bundled subpath,
+ * #3421) does not import it. The rollout takes it as `editTs`.
+ */
+
+import * as ts from "typescript";
+import type { PinCallResult, PinEditResult, PinRequest } from "./edit";
+import { movePin } from "./source";
+
+function propertyName(name: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
+  return undefined;
+}
+
+function stringInitializer(obj: ts.ObjectLiteralExpression, key: string): ts.StringLiteral | ts.NoSubstitutionTemplateLiteral | "expression" | undefined {
+  for (const p of obj.properties) {
+    if (!ts.isPropertyAssignment(p) || propertyName(p.name) !== key) continue;
+    const init = p.initializer;
+    return ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init) ? init : "expression";
+  }
+  return undefined;
+}
+
+/** Write a value as a literal with the same quote the old one used. */
+function quote(value: string, old: ts.StringLiteral | ts.NoSubstitutionTemplateLiteral, file: ts.SourceFile): string {
+  const q = old.getText(file)[0]!;
+  const escaped = value.replace(/\\/g, "\\\\").replaceAll(q, `\\${q}`);
+  return `${q}${q === "`" ? escaped.replace(/\$\{/g, "\\${") : escaped}${q}`;
+}
+
+/** Move `request.module`'s pin in one TypeScript file. */
+export function editPinsInTs(text: string, file: string, request: PinRequest): PinEditResult {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const calls: PinCallResult[] = [];
+  const splices: Array<{ start: number; end: number; text: string }> = [];
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isObjectLiteralExpression(node)) {
+      const source = stringInitializer(node, "source");
+      const version = stringInitializer(node, "version");
+      if (source && source !== "expression") {
+        const call = `line ${sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1}`;
+        const move = movePin(source.text, version && version !== "expression" ? version.text : undefined, request);
+        if (move) {
+          if (version === "expression") {
+            calls.push({ outcome: "refused", reason: "version is an expression, not a string literal", file, call });
+          } else if (move.outcome === "moved") {
+            if (move.source !== source.text) splices.push({ start: source.getStart(sf), end: source.getEnd(), text: quote(move.source, source, sf) });
+            if (version && move.version !== undefined && move.version !== version.text) splices.push({ start: version.getStart(sf), end: version.getEnd(), text: quote(move.version, version, sf) });
+            calls.push({ ...move, file, call });
+          } else {
+            calls.push({ ...move, file, call });
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  let content = text;
+  for (const s of splices.sort((a, b) => b.start - a.start)) content = content.slice(0, s.start) + s.text + content.slice(s.end);
+  return { content, calls };
+}

package/src/pin/edit.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, test } from "vitest";
+import { loadHcl2json } from "@intentius/chant/terraform/hcl2json";
+import { editPins, type PinRequest } from "./edit";
+import { readModulePin } from "./source";
+
+const parser = await loadHcl2json();
+
+const OCI = "oci://registry.example.com/modules/vpc";
+const REGISTRY = "app.terraform.io/acme/vpc/aws";
+const GIT = "git::https://github.com/acme/modules.git//vpc";
+
+/**
+ * One row: a file, the request, and the whole file the edit must produce. The
+ * expected text is the entire file, so every row also proves the bytes around
+ * the pin are untouched: comments, heredocs, other modules, spacing.
+ */
+interface Row {
+  name: string;
+  file: string;
+  request: PinRequest;
+  before: string;
+  after: string;
+  outcomes: string[];
+  reason?: RegExp;
+}
+
+const ROWS: Row[] = [
+  {
+    name: "an oci tag",
+    file: "main.tf",
+    request: { module: OCI, from: "1.3.0", to: "1.4.0" },
+    before: `module "vpc" {\n  source = "${OCI}?tag=1.3.0"\n  cidr   = "10.0.0.0/16"\n}\n`,
+    after: `module "vpc" {\n  source = "${OCI}?tag=1.4.0"\n  cidr   = "10.0.0.0/16"\n}\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "an oci digest",
+    file: "main.tf",
+    request: { module: OCI, from: `sha256:${"a".repeat(64)}`, to: `sha256:${"b".repeat(64)}` },
+    before: `module "vpc" {\n  source = "${OCI}?digest=sha256:${"a".repeat(64)}"\n}\n`,
+    after: `module "vpc" {\n  source = "${OCI}?digest=sha256:${"b".repeat(64)}"\n}\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "an oci tag moved to a digest changes the argument",
+    file: "main.tf",
+    request: { module: OCI, from: "1.3.0", to: `sha256:${"c".repeat(64)}` },
+    before: `module "vpc" { source = "${OCI}?tag=1.3.0" }\n`,
+    after: `module "vpc" { source = "${OCI}?digest=sha256:${"c".repeat(64)}" }\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "a git ref, with comments and other modules left byte for byte",
+    file: "main.tf",
+    request: { module: GIT, from: "v1.3.0", to: "v1.4.0" },
+    before: [
+      `# source = "${GIT}?ref=v1.3.0" in a comment is not a call`,
+      `module "vpc" {`,
+      `  source = "${GIT}?ref=v1.3.0" # pinned`,
+      `  /* version = "1.3.0" */`,
+      `  tags = { note = "source = \\"${GIT}?ref=v1.3.0\\"" }`,
+      `}`,
+      ``,
+      `module "other" {`,
+      `  source = "${GIT.replace("vpc", "dns")}?ref=v1.3.0"`,
+      `}`,
+      ``,
+    ].join("\n"),
+    after: [
+      `# source = "${GIT}?ref=v1.3.0" in a comment is not a call`,
+      `module "vpc" {`,
+      `  source = "${GIT}?ref=v1.4.0" # pinned`,
+      `  /* version = "1.3.0" */`,
+      `  tags = { note = "source = \\"${GIT}?ref=v1.3.0\\"" }`,
+      `}`,
+      ``,
+      `module "other" {`,
+      `  source = "${GIT.replace("vpc", "dns")}?ref=v1.3.0"`,
+      `}`,
+      ``,
+    ].join("\n"),
+    outcomes: ["moved"],
+  },
+  {
+    name: "an exact registry version, and a second call of the same module",
+    file: "main.tf",
+    request: { module: REGISTRY, from: "1.3.0", to: "1.4.0" },
+    before: `module "a" {\n  source  = "${REGISTRY}"\n  version = "1.3.0"\n}\n\nmodule "b" {\n  source  = "${REGISTRY}"\n  version = "= 1.3.0"\n  description = <<EOT\nversion = "1.3.0"\nEOT\n}\n`,
+    after: `module "a" {\n  source  = "${REGISTRY}"\n  version = "1.4.0"\n}\n\nmodule "b" {\n  source  = "${REGISTRY}"\n  version = "= 1.4.0"\n  description = <<EOT\nversion = "1.3.0"\nEOT\n}\n`,
+    outcomes: ["moved", "moved"],
+  },
+  {
+    name: "a terragrunt source with ?ref=",
+    file: "live/prod/vpc/terragrunt.hcl",
+    request: { module: GIT, from: "v1.3.0", to: "v1.4.0" },
+    before: `include "root" {\n  path = find_in_parent_folders()\n}\n\nterraform {\n  source = "${GIT}?ref=v1.3.0"\n}\n\ninputs = {\n  name = "vpc"\n}\n`,
+    after: `include "root" {\n  path = find_in_parent_folders()\n}\n\nterraform {\n  source = "${GIT}?ref=v1.4.0"\n}\n\ninputs = {\n  name = "vpc"\n}\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "a terragrunt tfr source with ?version=",
+    file: "terragrunt.hcl",
+    request: { module: "tfr:///terraform-aws-modules/vpc/aws", from: "5.1.0", to: "5.2.0" },
+    before: `terraform {\n  source = "tfr:///terraform-aws-modules/vpc/aws?version=5.1.0"\n}\n`,
+    after: `terraform {\n  source = "tfr:///terraform-aws-modules/vpc/aws?version=5.2.0"\n}\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "a terragrunt oci source",
+    file: "terragrunt.hcl",
+    request: { module: OCI, from: "1.3.0", to: "1.4.0" },
+    before: `terraform { source = "${OCI}?tag=1.3.0" }\n`,
+    after: `terraform { source = "${OCI}?tag=1.4.0" }\n`,
+    outcomes: ["moved"],
+  },
+  {
+    name: "a floating constraint is refused with its reason",
+    file: "main.tf",
+    request: { module: REGISTRY, from: "1.3.0", to: "1.4.0" },
+    before: `module "a" {\n  source  = "${REGISTRY}"\n  version = "~> 1.3"\n}\n`,
+    after: `module "a" {\n  source  = "${REGISTRY}"\n  version = "~> 1.3"\n}\n`,
+    outcomes: ["refused"],
+    reason: /version "~> 1.3" is a constraint, not a pin/,
+  },
+  {
+    name: "a comma-separated range is refused",
+    file: "main.tf",
+    request: { module: REGISTRY, from: "1.3.0", to: "1.4.0" },
+    before: `module "a" {\n  source  = "${REGISTRY}"\n  version = ">= 1.3.0, < 2.0.0"\n}\n`,
+    after: `module "a" {\n  source  = "${REGISTRY}"\n  version = ">= 1.3.0, < 2.0.0"\n}\n`,
+    outcomes: ["refused"],
+    reason: /is a constraint, not a pin/,
+  },
+  {
+    name: "an unpinned oci source is refused",
+    file: "main.tf",
+    request: { module: OCI, from: "1.3.0", to: "1.4.0" },
+    before: `module "vpc" {\n  source = "${OCI}"\n}\n`,
+    after: `module "vpc" {\n  source = "${OCI}"\n}\n`,
+    outcomes: ["refused"],
+    reason: /names no tag or digest/,
+  },
+  {
+    name: "a terragrunt source built from an expression is refused",
+    file: "terragrunt.hcl",
+    request: { module: GIT, from: "v1.3.0", to: "v1.4.0" },
+    before: `locals {\n  ref = "v1.3.0"\n}\nterraform {\n  source = "${GIT}?ref=\${local.ref}"\n}\n`,
+    after: `locals {\n  ref = "v1.3.0"\n}\nterraform {\n  source = "${GIT}?ref=\${local.ref}"\n}\n`,
+    outcomes: ["refused"],
+    reason: /is an expression/,
+  },
+  {
+    name: "a call at the new version already is reported and left",
+    file: "main.tf",
+    request: { module: OCI, from: "1.3.0", to: "1.4.0" },
+    before: `module "vpc" {\n  source = "${OCI}?tag=1.4.0"\n}\n`,
+    after: `module "vpc" {\n  source = "${OCI}?tag=1.4.0"\n}\n`,
+    outcomes: ["already"],
+  },
+  {
+    name: "a call pinned at a third version is reported and left",
+    file: "main.tf",
+    request: { module: OCI, from: "1.3.0", to: "1.4.0" },
+    before: `module "vpc" {\n  source = "${OCI}?tag=1.2.0"\n}\n`,
+    after: `module "vpc" {\n  source = "${OCI}?tag=1.2.0"\n}\n`,
+    outcomes: ["elsewhere"],
+  },
+];
+
+describe("editPins (#3189)", () => {
+  test.each(ROWS)("$name", async (row) => {
+    const result = await editPins(row.before, row.file, row.request, parser);
+    expect(result.content).toBe(row.after);
+    expect(result.calls.map((c) => c.outcome)).toEqual(row.outcomes);
+    if (row.reason) {
+      const refused = result.calls.find((c) => c.outcome === "refused");
+      expect(refused && "reason" in refused ? refused.reason : "").toMatch(row.reason);
+    }
+  });
+});
+
+describe("readModulePin", () => {
+  test.each([
+    [`${OCI}?tag=1.3.0`, undefined, { module: OCI, pin: "1.3.0", param: "tag" }],
+    [`oci://localhost:4890/largeset/shared?tag=1.0.0`, undefined, { module: "oci://localhost:4890/largeset/shared", pin: "1.0.0", param: "tag" }],
+    [`${GIT}?depth=1&ref=v2`, undefined, { module: `${GIT}?depth=1`, pin: "v2", param: "ref" }],
+    [REGISTRY, "1.3.0", { module: REGISTRY, pin: "1.3.0", at: "version" }],
+    [REGISTRY, "= v1.3.0", { module: REGISTRY, pin: "v1.3.0", at: "version" }],
+    [REGISTRY, "~> 1.3", { module: REGISTRY, pin: null }],
+    [REGISTRY, ">= 1.3", { module: REGISTRY, pin: null }],
+    [REGISTRY, undefined, { module: REGISTRY, pin: null }],
+    [REGISTRY, "${var.vpc_version}", { module: REGISTRY, pin: null, unpinned: expect.stringContaining("is an expression") }],
+    [GIT, undefined, { module: GIT, pin: null }],
+    ["./modules/vpc", undefined, { module: "./modules/vpc", pin: null }],
+    [`${OCI}?tag=1&digest=sha256:${"a".repeat(64)}`, undefined, { module: OCI, pin: null }],
+  ] as const)("%s %s", (source, version, want) => {
+    expect(readModulePin(source, version)).toMatchObject(want);
+  });
+});

package/src/pin/edit.ts

@@ -0,0 +1,157 @@
+/**
+ * The pin edit for hand-written HCL (#3189): move one module's pin from an old
+ * version to a new one in a `.tf` file or a `terragrunt.hcl`, and leave every
+ * other byte of the file as it was.
+ *
+ * Three steps, each one a check on the last:
+ *
+ * 1. The HCL reader (`@cdktn/hcl2json`, the parser the rest of this lexicon
+ *    reads `.tf` with) parses the file. Its tree says which calls exist and
+ *    what each one's `source` and `version` are: `module "<name>"` blocks in a
+ *    `.tf`, and the `terraform` block's `source` in a `terragrunt.hcl`.
+ * 2. `./source.ts` decides, per call, whether it names the module and how its
+ *    pin moves. `./scan.ts` finds the byte offsets of the literal to rewrite,
+ *    and its unescaped content has to equal the value the reader returned, or
+ *    the call is refused rather than guessed at.
+ * 3. The edited text is parsed again. Its tree has to equal the first tree
+ *    with only the moved values changed. Anything else throws, and nothing is
+ *    written.
+ *
+ * The parser is passed in rather than imported. It is a 1.8 MB wasm package
+ * that core loads lazily (`loadHcl2json`), and a caller that bundles this
+ * module (terragucci's `tf-rollout` stage, #3421) decides how it is loaded.
+ */
+
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { movePin, type PinMove } from "./source";
+import { escapeHcl, scanBlocks, unescapeHcl, type ScannedAttribute, type ScannedBlock } from "./scan";
+
+/** What to move: a module, named by its source without the pin, from one pin to another. */
+export interface PinRequest {
+  module: string;
+  from: string;
+  to: string;
+}
+
+/** One module call the edit looked at, and what happened to it. */
+export type PinCallResult = PinMove & {
+  /** The file, as the caller named it. */
+  file: string;
+  /** `module.<name>` in a `.tf`, `terraform` in a `terragrunt.hcl`, or `line <n>` in TypeScript source. */
+  call: string;
+};
+
+/** The edited text and every call that names the module. */
+export interface PinEditResult {
+  content: string;
+  calls: PinCallResult[];
+}
+
+/** Whether a file is read as a Terragrunt configuration rather than a `.tf` file. */
+export function isTerragruntFile(file: string): boolean {
+  return file === "terragrunt.hcl" || file.endsWith("/terragrunt.hcl");
+}
+
+type Tree = Record<string, unknown>;
+
+interface Site {
+  call: string;
+  block: ScannedBlock;
+  /** The reader's body for this call, which the verification re-reads. */
+  body: Record<string, unknown>;
+}
+
+function attr(block: ScannedBlock, name: string): ScannedAttribute | undefined {
+  return block.attributes.find((a) => a.name === name);
+}
+
+/** Pair each call in the reader's tree with the block the scanner found for it. */
+function sites(tree: Tree, blocks: ScannedBlock[], terragrunt: boolean): Site[] {
+  const out: Site[] = [];
+  if (terragrunt) {
+    const bodies = (tree.terraform as Record<string, unknown>[] | undefined) ?? [];
+    const scanned = blocks.filter((b) => b.type === "terraform" && b.labels.length === 0);
+    bodies.forEach((body, k) => {
+      if (scanned[k]) out.push({ call: "terraform", block: scanned[k]!, body });
+    });
+    return out;
+  }
+  const modules = (tree.module as Record<string, Record<string, unknown>[]> | undefined) ?? {};
+  for (const [name, bodies] of Object.entries(modules)) {
+    const scanned = blocks.filter((b) => b.type === "module" && b.labels.length === 1 && b.labels[0] === name);
+    bodies.forEach((body, k) => {
+      if (scanned[k]) out.push({ call: `module.${name}`, block: scanned[k]!, body });
+    });
+  }
+  return out.sort((a, b) => a.block.start - b.block.start);
+}
+
+/** Pin edits are applied back to front, so earlier offsets stay valid. */
+interface Splice {
+  start: number;
+  end: number;
+  text: string;
+}
+
+/**
+ * Move `request.module`'s pin in one file. Calls that name another module are
+ * left alone and not reported. A call that names the module and cannot move
+ * is reported with its reason and left as it was.
+ */
+export async function editPins(text: string, file: string, request: PinRequest, parser: Hcl2Json): Promise<PinEditResult> {
+  const terragrunt = isTerragruntFile(file);
+  const tree = (await parser.parse(file, text)) as Tree;
+  const blocks = scanBlocks(text, file);
+  const calls: PinCallResult[] = [];
+  const splices: Splice[] = [];
+  const expected = structuredClone(tree);
+  const expectedSites = sites(expected, scanBlocks(text, file), terragrunt);
+
+  sites(tree, blocks, terragrunt).forEach((site, index) => {
+    const source = site.body.source;
+    const version = site.body.version;
+    if (typeof source !== "string") return;
+    const move = movePin(source, typeof version === "string" ? version : undefined, request);
+    if (!move) return;
+    const at = { file, call: site.call };
+    if (move.outcome !== "moved") {
+      calls.push({ ...move, ...at });
+      return;
+    }
+    const edits: Array<[name: "source" | "version", value: string]> = [];
+    if (move.source !== source) edits.push(["source", move.source]);
+    if (move.version !== undefined && move.version !== version) edits.push(["version", move.version]);
+    for (const [name] of edits) {
+      const scanned = attr(site.block, name);
+      const was = site.body[name] as string;
+      if (!scanned?.literal || unescapeHcl(scanned.literal.raw) !== was) {
+        calls.push({ outcome: "refused", reason: `${name} is not a plain string literal, so there is no one place to write the pin`, ...at });
+        return;
+      }
+    }
+    for (const [name, value] of edits) {
+      const literal = attr(site.block, name)!.literal!;
+      splices.push({ start: literal.start, end: literal.end, text: rewriteLiteral(literal.raw, site.body[name] as string, value) });
+      expectedSites[index]!.body[name] = value;
+    }
+    calls.push({ ...move, ...at });
+  });
+
+  let content = text;
+  for (const s of splices.sort((a, b) => b.start - a.start)) content = content.slice(0, s.start) + s.text + content.slice(s.end);
+  if (splices.length > 0) {
+    const reread = (await parser.parse(file, content)) as Tree;
+    if (JSON.stringify(reread) !== JSON.stringify(expected)) {
+      throw new Error(`${file}: the pin edit would change more than the pin, so nothing was written`);
+    }
+  }
+  return { content, calls };
+}
+
+/**
+ * The new literal content. When the old literal needed no escapes, the old
+ * value's text is replaced in place, so any spacing (`= 1.3.0`) survives.
+ */
+function rewriteLiteral(raw: string, was: string, value: string): string {
+  return raw === was ? value : escapeHcl(value);
+}

package/src/pin/forge.ts

@@ -0,0 +1,85 @@
+/**
+ * What a pin-bump rollout asks the forge (#3189): find a wave's pull request
+ * by its branch, open one, and read the checks on the commit a merge made.
+ *
+ * The default answers through `gh`, the way core's `proposeWorkspaceUpgrade`
+ * (#2550) opens its pull request: `gh pr list --head`, `gh pr create`, and
+ * `gh api` for the commit's check runs and statuses. A test, or a caller with
+ * its own forge client, passes a {@link PinForge} instead.
+ */
+
+import type { CommandRunner } from "@intentius/chant/op/activities/propose-upgrade";
+
+/** A wave's pull request, as the forge reports it. */
+export interface PinPullRequest {
+  url: string;
+  state: "open" | "merged" | "closed";
+  body: string;
+  /** The commit the merge made on the base branch, once merged. */
+  mergeCommit?: string;
+}
+
+/** One check or status on a commit. */
+export interface PinCommitCheck {
+  name: string;
+  state: "success" | "pending" | "failure";
+}
+
+export interface PinForge {
+  /** The newest pull request whose head is `branch`, in any state, or null. */
+  findPullRequest(branch: string): Promise<PinPullRequest | null>;
+  /** Open a pull request and return its URL. */
+  createPullRequest(input: { base: string; head: string; title: string; body: string }): Promise<string>;
+  /** The checks and statuses on a commit. */
+  commitChecks(sha: string): Promise<PinCommitCheck[]>;
+}
+
+const CHECK_STATE: Record<string, PinCommitCheck["state"]> = {
+  success: "success",
+  neutral: "success",
+  skipped: "success",
+  failure: "failure",
+  cancelled: "failure",
+  timed_out: "failure",
+  action_required: "failure",
+  startup_failure: "failure",
+  stale: "failure",
+  error: "failure",
+  pending: "pending",
+};
+
+/** A {@link PinForge} over `gh`, run in `repo`. */
+export function ghPinForge(run: CommandRunner, repo: string): PinForge {
+  return {
+    async findPullRequest(branch) {
+      const out = await run("gh", ["pr", "list", "--head", branch, "--state", "all", "--limit", "1", "--json", "url,state,body,mergeCommit"], repo);
+      const list = JSON.parse(out || "[]") as Array<{ url: string; state: string; body?: string; mergeCommit?: { oid?: string } | null }>;
+      const pr = list[0];
+      if (!pr) return null;
+      const state = pr.state.toLowerCase() === "merged" ? "merged" : pr.state.toLowerCase() === "open" ? "open" : "closed";
+      return { url: pr.url, state, body: pr.body ?? "", ...(pr.mergeCommit?.oid ? { mergeCommit: pr.mergeCommit.oid } : {}) };
+    },
+    async createPullRequest({ base, head, title, body }) {
+      const out = await run("gh", ["pr", "create", "--base", base, "--head", head, "--title", title, "--body", body], repo);
+      return out.trim().split("\n").pop() ?? "";
+    },
+    async commitChecks(sha) {
+      const checks: PinCommitCheck[] = [];
+      const runs = await run("gh", ["api", "--paginate", `repos/{owner}/{repo}/commits/${sha}/check-runs`, "--jq", ".check_runs[] | [.name, .status, (.conclusion // \"\")] | @tsv"], repo);
+      for (const line of runs.split("\n").filter(Boolean)) {
+        const [name, status, conclusion] = line.split("\t");
+        checks.push({ name: name!, state: status === "completed" ? (CHECK_STATE[conclusion ?? ""] ?? "failure") : "pending" });
+      }
+      // Statuses come newest first; the first one per context is its state.
+      const statuses = await run("gh", ["api", "--paginate", `repos/{owner}/{repo}/commits/${sha}/statuses`, "--jq", ".[] | [.context, .state] | @tsv"], repo);
+      const seen = new Set<string>();
+      for (const line of statuses.split("\n").filter(Boolean)) {
+        const [name, state] = line.split("\t");
+        if (seen.has(name!)) continue;
+        seen.add(name!);
+        checks.push({ name: name!, state: CHECK_STATE[state ?? ""] ?? "pending" });
+      }
+      return checks;
+    },
+  };
+}

package/src/pin/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Pin-bump rollouts (#3189): the pin edit, the wave plan, and the run that
+ * opens one pull request per wave.
+ *
+ * This subpath, `@intentius/chant-lexicon-terraform/pin`, bundles without the
+ * TypeScript toolchain, zod, or chant's fold, lint and codegen modules, so
+ * terragucci's `tf-rollout` stage can run it from one bundled file (#3421).
+ * `./bundle.test.ts` holds it to that. The HCL parser is passed in, and the
+ * TypeScript editor for generated roots lives in `./edit-ts.ts`, which this
+ * index does not import.
+ */
+
+export { readModulePin, movePin, moduleOf, exactVersion, isPinValue, checkPinRequest } from "./source";
+export type { ModuleCallPin, PinMove, PinParam } from "./source";
+export { editPins, isTerragruntFile } from "./edit";
+export type { PinRequest, PinCallResult, PinEditResult } from "./edit";
+export { planPinWaves, wavesFromChoudoufu, restrictWaves, terragruntDependencies, PinWavePlanError } from "./waves";
+export type { PinRoot, PinWave } from "./waves";
+export { ghPinForge } from "./forge";
+export type { PinForge, PinPullRequest, PinCommitCheck } from "./forge";
+export { runPinRollout, renderPinRollout, pinWaveBranch } from "./rollout";
+export type { PinRolloutOptions, PinRolloutResult, PinRolloutMode, PinRootState, PinWaveState, PinWaveStatus, TsPinEditor } from "./rollout";