@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/pin/scan.ts

@@ -0,0 +1,309 @@
+/**
+ * Byte offsets for the attribute values the pin edit rewrites (#3189).
+ *
+ * `@cdktn/hcl2json` is the reader that says what a file means, and the pin
+ * edit asks it first (`./edit.ts`). It gives back values and no positions
+ * (`../hcl/value.ts` says why), so it cannot say WHERE in the file a
+ * `source` or `version` literal sits. This lexer answers only that: it walks
+ * the raw text token by token, skipping comments, quoted strings, template
+ * interpolations and heredocs, counts braces, and records each top-level
+ * block and the plain string literal of each of its own attributes, with the
+ * literal's offsets.
+ *
+ * It is an HCL tokenizer, not a pattern match over lines: a `source =` inside
+ * a comment, a heredoc or another string is never a match, and a block opened
+ * on the same line as its attributes reads the same as one split over lines.
+ * What it finds is checked against the reader before anything is written:
+ * the literal's unescaped value has to equal what hcl2json read for that
+ * attribute, and the edited file has to parse to the same tree with only the
+ * pinned values changed.
+ */
+
+/** One plain string literal: the offsets of its content, quotes excluded. */
+export interface ScannedLiteral {
+  start: number;
+  end: number;
+  /** The content as written, escapes included. */
+  raw: string;
+}
+
+/** One attribute of a block body. `literal` is set when the value is a single string with no interpolation. */
+export interface ScannedAttribute {
+  name: string;
+  literal?: ScannedLiteral;
+}
+
+/** One top-level block: `module "vpc" { ... }`, `terraform { ... }`. */
+export interface ScannedBlock {
+  type: string;
+  labels: string[];
+  /** Offset of the block's type keyword. */
+  start: number;
+  /** Offset just past the closing brace. */
+  end: number;
+  /** The block body's own attributes, in file order. Nested blocks' attributes are not included. */
+  attributes: ScannedAttribute[];
+}
+
+type Token =
+  | { kind: "ident"; value: string; start: number; end: number }
+  | { kind: "string"; start: number; end: number; raw: string; template: boolean }
+  | { kind: "punct"; value: string; start: number; end: number }
+  | { kind: "newline"; start: number; end: number }
+  | { kind: "other"; start: number; end: number };
+
+const IDENT_START = /[A-Za-z_]/;
+const IDENT_PART = /[A-Za-z0-9_-]/;
+
+/** Thrown when the text is not well-formed enough to place an edit in. */
+export class HclScanError extends Error {
+  constructor(file: string, message: string) {
+    super(`${file}: ${message}`);
+    this.name = "HclScanError";
+  }
+}
+
+/**
+ * Skip a quoted string starting at `i` (the opening quote). Returns the index
+ * just past the closing quote, and whether a `${` or `%{` template appears.
+ */
+function skipString(text: string, i: number, file: string): { end: number; template: boolean } {
+  let j = i + 1;
+  let template = false;
+  while (j < text.length) {
+    const c = text[j];
+    if (c === "\\") {
+      j += 2;
+      continue;
+    }
+    if (c === '"') return { end: j + 1, template };
+    if (c === "\n") throw new HclScanError(file, `unterminated string at offset ${i}`);
+    if ((c === "$" || c === "%") && text[j + 1] === "{") {
+      // `$${` and `%%{` are escapes for a literal `${` and `%{`.
+      if (text[j - 1] === c) {
+        j += 2;
+        continue;
+      }
+      template = true;
+      j = skipTemplate(text, j + 2, file);
+      continue;
+    }
+    j++;
+  }
+  throw new HclScanError(file, `unterminated string at offset ${i}`);
+}
+
+/** Skip a template interpolation body starting just inside `${`. Returns the index past its `}`. */
+function skipTemplate(text: string, i: number, file: string): number {
+  let depth = 1;
+  let j = i;
+  while (j < text.length) {
+    const c = text[j];
+    if (c === '"') {
+      j = skipString(text, j, file).end;
+      continue;
+    }
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return j + 1;
+    }
+    j++;
+  }
+  throw new HclScanError(file, `unterminated template at offset ${i}`);
+}
+
+function tokenize(text: string, file: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i]!;
+    if (c === "\n") {
+      tokens.push({ kind: "newline", start: i, end: i + 1 });
+      i++;
+      continue;
+    }
+    if (c === " " || c === "\t" || c === "\r") {
+      i++;
+      continue;
+    }
+    if (c === "#" || (c === "/" && text[i + 1] === "/")) {
+      while (i < text.length && text[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      const close = text.indexOf("*/", i + 2);
+      if (close < 0) throw new HclScanError(file, `unterminated comment at offset ${i}`);
+      // A block comment spanning lines still ends a statement where a newline would.
+      if (text.slice(i, close).includes("\n")) tokens.push({ kind: "newline", start: i, end: close + 2 });
+      i = close + 2;
+      continue;
+    }
+    if (c === '"') {
+      const { end, template } = skipString(text, i, file);
+      tokens.push({ kind: "string", start: i, end, raw: text.slice(i + 1, end - 1), template });
+      i = end;
+      continue;
+    }
+    if (c === "<" && text[i + 1] === "<" && /[-A-Za-z_]/.test(text[i + 2] ?? "")) {
+      const m = /^<<-?([A-Za-z_][A-Za-z0-9_-]*)[ \t]*\r?\n/.exec(text.slice(i));
+      if (m) {
+        const marker = m[1]!;
+        let j = i + m[0].length;
+        for (;;) {
+          const lineEnd = text.indexOf("\n", j);
+          const line = text.slice(j, lineEnd < 0 ? text.length : lineEnd);
+          if (line.trim() === marker) {
+            j = lineEnd < 0 ? text.length : lineEnd;
+            break;
+          }
+          if (lineEnd < 0) throw new HclScanError(file, `unterminated heredoc ${marker} at offset ${i}`);
+          j = lineEnd + 1;
+        }
+        tokens.push({ kind: "other", start: i, end: j });
+        i = j;
+        continue;
+      }
+    }
+    if (IDENT_START.test(c)) {
+      let j = i + 1;
+      while (j < text.length && IDENT_PART.test(text[j]!)) j++;
+      tokens.push({ kind: "ident", value: text.slice(i, j), start: i, end: j });
+      i = j;
+      continue;
+    }
+    const two = text.slice(i, i + 2);
+    if (two === "==" || two === "!=" || two === "<=" || two === ">=" || two === "=>" || two === "&&" || two === "||") {
+      tokens.push({ kind: "punct", value: two, start: i, end: i + 2 });
+      i += 2;
+      continue;
+    }
+    if ("{}[]()=,.:?".includes(c)) {
+      tokens.push({ kind: "punct", value: c, start: i, end: i + 1 });
+      i++;
+      continue;
+    }
+    tokens.push({ kind: "other", start: i, end: i + 1 });
+    i++;
+  }
+  return tokens;
+}
+
+const OPEN = new Set(["{", "[", "("]);
+const CLOSE = new Set(["}", "]", ")"]);
+
+/** Every top-level block in `text`, with its own attributes' literals. */
+export function scanBlocks(text: string, file: string): ScannedBlock[] {
+  const tokens = tokenize(text, file);
+  const blocks: ScannedBlock[] = [];
+  let i = 0;
+  const atStatementStart = (k: number) => k === 0 || tokens[k - 1]!.kind === "newline" || (tokens[k - 1]!.kind === "punct" && (tokens[k - 1] as { value: string }).value === "{");
+
+  while (i < tokens.length) {
+    const t = tokens[i]!;
+    if (t.kind !== "ident" || !atStatementStart(i)) {
+      i = skipStatement(tokens, i);
+      continue;
+    }
+    // A block header: a type, then string or identifier labels, then `{`.
+    const labels: string[] = [];
+    let j = i + 1;
+    while (j < tokens.length) {
+      const l = tokens[j]!;
+      if (l.kind === "string" && !l.template) labels.push(l.raw);
+      else if (l.kind === "ident") labels.push(l.value);
+      else break;
+      j++;
+    }
+    const brace = tokens[j];
+    if (!brace || brace.kind !== "punct" || brace.value !== "{") {
+      i = skipStatement(tokens, i);
+      continue;
+    }
+    const { end, attributes } = readBody(tokens, j, file);
+    blocks.push({ type: t.value, labels, start: t.start, end: tokens[end]!.end, attributes });
+    i = end + 1;
+  }
+  return blocks;
+}
+
+/** Skip to the token after the end of the statement starting at `i`: the next newline at bracket depth 0. */
+function skipStatement(tokens: Token[], i: number): number {
+  let depth = 0;
+  let j = i;
+  while (j < tokens.length) {
+    const t = tokens[j]!;
+    if (t.kind === "punct" && OPEN.has(t.value)) depth++;
+    else if (t.kind === "punct" && CLOSE.has(t.value)) depth = Math.max(0, depth - 1);
+    else if (t.kind === "newline" && depth === 0) return j + 1;
+    j++;
+  }
+  return j;
+}
+
+/** Read a block body whose `{` is at `open`. Returns the index of the matching `}` and the body's own attributes. */
+function readBody(tokens: Token[], open: number, file: string): { end: number; attributes: ScannedAttribute[] } {
+  const attributes: ScannedAttribute[] = [];
+  let depth = 1;
+  let j = open + 1;
+  let statementStart = true;
+  while (j < tokens.length) {
+    const t = tokens[j]!;
+    if (t.kind === "newline") {
+      if (depth === 1) statementStart = true;
+      j++;
+      continue;
+    }
+    if (depth === 1 && statementStart && t.kind === "ident") {
+      const eq = tokens[j + 1];
+      if (eq && eq.kind === "punct" && eq.value === "=") {
+        const value = tokens[j + 2];
+        const after = tokens[j + 3];
+        const ends = !after || after.kind === "newline" || (after.kind === "punct" && after.value === "}");
+        const literal = value && value.kind === "string" && !value.template && ends ? { start: value.start + 1, end: value.end - 1, raw: value.raw } : undefined;
+        attributes.push({ name: t.value, ...(literal ? { literal } : {}) });
+      }
+    }
+    statementStart = false;
+    if (t.kind === "punct" && OPEN.has(t.value)) depth++;
+    else if (t.kind === "punct" && CLOSE.has(t.value)) {
+      depth--;
+      if (depth === 0) return { end: j, attributes };
+    }
+    j++;
+  }
+  throw new HclScanError(file, `unbalanced braces: a block opened at offset ${tokens[open]!.start} never closes`);
+}
+
+/** Undo HCL's string escapes, so a literal's raw text compares to the value the reader returned. */
+export function unescapeHcl(raw: string): string {
+  let out = "";
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i]!;
+    if (c === "\\") {
+      const n = raw[i + 1];
+      i++;
+      if (n === "n") out += "\n";
+      else if (n === "t") out += "\t";
+      else if (n === "r") out += "\r";
+      else if (n === "u" || n === "U") {
+        const len = n === "u" ? 4 : 8;
+        out += String.fromCodePoint(parseInt(raw.slice(i + 1, i + 1 + len), 16));
+        i += len;
+      } else out += n ?? "";
+      continue;
+    }
+    if ((c === "$" || c === "%") && raw[i + 1] === c && raw[i + 2] === "{") {
+      out += `${c}{`;
+      i += 2;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/** Write a value as the content of an HCL string literal. */
+export function escapeHcl(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\$\{/g, "$${").replace(/%\{/g, "%%{");
+}

package/src/pin/source.ts

@@ -0,0 +1,206 @@
+/**
+ * Where a module call keeps its pin, and how the pin moves (#3189).
+ *
+ * A module call names a module and, if it is pinned, one exact version of it.
+ * The version sits in one of two places:
+ *
+ * - the `version` argument, beside a registry `source`
+ *   (`source = "app.terraform.io/acme/vpc/aws"`, `version = "1.3.0"`);
+ * - a query argument of the `source` itself: OpenTofu's `oci://` sources take
+ *   `?tag=` or `?digest=`, a git source takes `?ref=`, and Terragrunt's
+ *   `tfr://` source takes `?version=`.
+ *
+ * The module's identity is the source with the pin taken out, so
+ * `oci://r.example.com/m/vpc?tag=1.3.0` and `oci://r.example.com/m/vpc?tag=1.4.0`
+ * call the same module.
+ *
+ * A `version` constraint (`~> 1.4`, `>= 1.4, < 2`) is not a pin. An upstream
+ * release changes what such a root runs with no diff to review, and there is
+ * no single version to move, so the call is refused with that reason. The
+ * same holds for a call with no pin at all.
+ *
+ * OpenTofu writes an OCI pin as a query argument
+ * (https://opentofu.org/docs/language/modules/sources/#oci-distribution-registries),
+ * not as a `:tag` or `@sha256:` suffix on the repository, so the query form is
+ * the one read here.
+ *
+ * This module is pure string work over values the HCL reader has already
+ * parsed. Finding those values in a file, and writing the new ones back, is
+ * `./edit.ts`. #3190 adds an `oci` kind to the lint classifier
+ * (`../lint/post-synth/module-source.ts`) with the same parse; the two can
+ * share one once both have landed.
+ */
+
+/** The query arguments that carry a pin. */
+export type PinParam = "tag" | "digest" | "ref" | "version";
+
+/** What a module call pins, read from its `source` and `version`. */
+export interface ModuleCallPin {
+  /** The module the call names: its `source` with the pin argument taken out. */
+  module: string;
+  /** Where the pin is: the `version` argument, or a query argument of `source`. */
+  at: "version" | "source";
+  /** The query argument holding the pin, when `at` is `source`. */
+  param?: PinParam;
+  /** The pinned version, tag, digest or ref. Null when there is no pin to move. */
+  pin: string | null;
+  /** Why the call has no pin to move, when `pin` is null. */
+  unpinned?: string;
+}
+
+/** The outcome of moving one call's pin. */
+export type PinMove =
+  | { outcome: "moved"; from: string; to: string; source: string; version?: string }
+  | { outcome: "already"; pin: string }
+  | { outcome: "elsewhere"; pin: string }
+  | { outcome: "refused"; reason: string };
+
+/** `1.4.0`, `v1.4.0`, `1.4`, `1.4.0-rc.1+build.5`: one exact version. */
+const EXACT_VERSION = /^v?\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+
+/** An OCI digest, `sha256:<hex>`. */
+const DIGEST = /^[a-z0-9]+(?:[.+_-][a-z0-9]+)*:[0-9a-fA-F]{32,}$/;
+
+/**
+ * The exact version a `version` argument pins, or null when it is a
+ * constraint. `1.4.0` and `= 1.4.0` are exact; `~> 1.4`, `>= 1.4` and
+ * `1.4.0, < 2` are not.
+ */
+export function exactVersion(constraint: string): string | null {
+  const trimmed = constraint.trim().replace(/^=\s*/, "");
+  return EXACT_VERSION.test(trimmed) ? trimmed : null;
+}
+
+/** Whether a value can be a pin's new value: an exact version, a tag, a ref or a digest, never a constraint. */
+export function isPinValue(value: string): boolean {
+  return value.length > 0 && !/[\s,<>~!=*^]/.test(value);
+}
+
+interface SplitSource {
+  base: string;
+  params: Array<{ key: string; value: string | undefined; raw: string }>;
+}
+
+function splitSource(source: string): SplitSource {
+  const q = source.indexOf("?");
+  if (q < 0) return { base: source, params: [] };
+  const params = source
+    .slice(q + 1)
+    .split("&")
+    .filter((raw) => raw.length > 0)
+    .map((raw) => {
+      const eq = raw.indexOf("=");
+      return eq < 0 ? { key: raw, value: undefined, raw } : { key: raw.slice(0, eq), value: decode(raw.slice(eq + 1)), raw };
+    });
+  return { base: source.slice(0, q), params };
+}
+
+function decode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function joinSource(base: string, raws: string[]): string {
+  return raws.length === 0 ? base : `${base}?${raws.join("&")}`;
+}
+
+function isLocal(source: string): boolean {
+  return source.startsWith("./") || source.startsWith("../");
+}
+
+function isOci(source: string): boolean {
+  return source.startsWith("oci://");
+}
+
+function isGit(source: string): boolean {
+  return source.startsWith("git::") || source.startsWith("git@") || /^(github\.com|bitbucket\.org)\//.test(source) || /\.git(\/\/|\?|$)/.test(source);
+}
+
+/** Read the pin a module call carries. `version` is the call's `version` argument, when it has one. */
+export function readModulePin(source: string, version?: string): ModuleCallPin {
+  const call = readPin(source, version);
+  const written = call.at === "version" ? version! : call.pin;
+  if (written != null && /[$%]\{/.test(written)) {
+    return { ...call, pin: null, unpinned: `the pin "${written}" is an expression, so there is no literal version to move` };
+  }
+  return call;
+}
+
+function readPin(source: string, version?: string): ModuleCallPin {
+  if (version !== undefined) {
+    const exact = exactVersion(version);
+    return exact
+      ? { module: source, at: "version", pin: exact }
+      : { module: source, at: "version", pin: null, unpinned: `version "${version}" is a constraint, not a pin: there is no one version to move` };
+  }
+  const { base, params } = splitSource(source);
+  const keep = (taken: string) => joinSource(base, params.filter((p) => p.key !== taken).map((p) => p.raw));
+  const find = (key: PinParam) => params.find((p) => p.key === key);
+
+  if (isOci(source)) {
+    const tag = find("tag");
+    const digest = find("digest");
+    if (tag && digest) return { module: joinSource(base, params.filter((p) => p.key !== "tag" && p.key !== "digest").map((p) => p.raw)), at: "source", pin: null, unpinned: "the oci source names both a tag and a digest" };
+    const p = digest ?? tag;
+    if (!p || !p.value) return { module: source, at: "source", pin: null, unpinned: "the oci source names no tag or digest, so it resolves whatever the registry calls latest" };
+    return { module: keep(p.key), at: "source", param: p.key as PinParam, pin: p.value };
+  }
+  const ref = find("ref");
+  if (ref?.value) return { module: keep("ref"), at: "source", param: "ref", pin: ref.value };
+  const ver = find("version");
+  if (ver?.value) {
+    const exact = exactVersion(ver.value);
+    return exact
+      ? { module: keep("version"), at: "source", param: "version", pin: exact }
+      : { module: keep("version"), at: "source", param: "version", pin: null, unpinned: `version "${ver.value}" is a constraint, not a pin: there is no one version to move` };
+  }
+  if (isLocal(source)) return { module: source, at: "source", pin: null, unpinned: "a local path has no version to pin" };
+  if (isGit(source)) return { module: source, at: "source", pin: null, unpinned: "the git source names no ref, so it follows the default branch" };
+  return { module: source, at: "source", pin: null, unpinned: "the source has no version argument and no pin in its address, so it resolves the newest release" };
+}
+
+/** Replace one query argument's value, keeping every other byte of the source. */
+function withParam(source: string, from: PinParam, to: PinParam, value: string): string {
+  const { base, params } = splitSource(source);
+  return joinSource(
+    base,
+    params.map((p) => (p.key === from ? `${to}=${value}` : p.raw)),
+  );
+}
+
+/**
+ * Move a call's pin from `from` to `to`, when the call names `module`.
+ * Returns null when it names another module. `version` keeps any `=` it was
+ * written with, so `= 1.3.0` becomes `= 1.4.0`.
+ */
+export function movePin(source: string, version: string | undefined, request: { module: string; from: string; to: string }): PinMove | null {
+  const call = readModulePin(source, version);
+  if (call.module !== request.module) return null;
+  if (call.pin === null) return { outcome: "refused", reason: call.unpinned ?? "no pin" };
+  if (call.pin === request.to) return { outcome: "already", pin: call.pin };
+  if (call.pin !== request.from) return { outcome: "elsewhere", pin: call.pin };
+  if (call.at === "version") {
+    const at = version!.lastIndexOf(call.pin);
+    return { outcome: "moved", from: request.from, to: request.to, source, version: version!.slice(0, at) + request.to + version!.slice(at + call.pin.length) };
+  }
+  // An oci pin moving between a tag and a digest changes which argument holds it.
+  const param: PinParam = call.param === "tag" || call.param === "digest" ? (DIGEST.test(request.to) ? "digest" : "tag") : call.param!;
+  return { outcome: "moved", from: request.from, to: request.to, source: withParam(source, call.param!, param, request.to) };
+}
+
+/** The module a source names, with any pin taken out, so a caller may name the module by a pinned source. */
+export function moduleOf(source: string): string {
+  return readModulePin(source).module;
+}
+
+/** Refuse a request whose `to` is not something a pin can hold. */
+export function checkPinRequest(request: { module: string; from: string; to: string }): void {
+  for (const [name, value] of [["from", request.from], ["to", request.to]] as const) {
+    if (!isPinValue(value)) throw new Error(`pin ${name} "${value}" is not an exact version, tag, ref or digest`);
+  }
+  if (request.from === request.to) throw new Error(`pin from and to are both "${request.to}": there is nothing to move`);
+  if (request.module.length === 0) throw new Error("pin module is empty: name the module's source without its pin");
+}

package/src/pin/waves.test.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import { loadHcl2json } from "@intentius/chant/terraform/hcl2json";
+import { planPinWaves, restrictWaves, terragruntDependencies, wavesFromChoudoufu, PinWavePlanError } from "./waves";
+
+/** choudoufu#1750's N=5 shape: e02 reads e01, e03 reads e02; e04 and e05 read nothing. */
+const N5 = [
+  { root: "estates/e01" },
+  { root: "estates/e02", dependsOn: ["estates/e01"] },
+  { root: "estates/e03", dependsOn: ["estates/e02"] },
+  { root: "estates/e04" },
+  { root: "estates/e05" },
+];
+
+describe("planPinWaves (#3189)", () => {
+  test("a canary list forms wave 1, and dependency order forms the rest", () => {
+    expect(planPinWaves(N5, ["estates/e04"])).toEqual([
+      { wave: 1, canary: true, roots: ["estates/e04"] },
+      { wave: 2, canary: false, roots: ["estates/e01", "estates/e05"] },
+      { wave: 3, canary: false, roots: ["estates/e02"] },
+      { wave: 4, canary: false, roots: ["estates/e03"] },
+    ]);
+  });
+
+  test("no reader lands in a wave before what it reads", () => {
+    const waves = planPinWaves(N5);
+    const waveOf = new Map(waves.flatMap((w) => w.roots.map((r) => [r, w.wave] as const)));
+    for (const r of N5) for (const d of r.dependsOn ?? []) expect(waveOf.get(d)!, `${r.root} after ${d}`).toBeLessThan(waveOf.get(r.root)!);
+  });
+
+  test("the canary wave whatever the graph order, even a root others read", () => {
+    expect(planPinWaves(N5, ["estates/e01"]).map((w) => w.roots)).toEqual([["estates/e01"], ["estates/e02", "estates/e04", "estates/e05"], ["estates/e03"]]);
+  });
+
+  test("a canary that reads a root outside the canaries is refused", () => {
+    expect(() => planPinWaves(N5, ["estates/e03"])).toThrow(/canary estates\/e03 depends on estates\/e02, which is not a canary/);
+  });
+
+  test("a canary that is not a root, and a cycle, are refused by name", () => {
+    expect(() => planPinWaves(N5, ["estates/e09"])).toThrow(PinWavePlanError);
+    expect(() =>
+      planPinWaves([
+        { root: "a", dependsOn: ["b"] },
+        { root: "b", dependsOn: ["a"] },
+      ]),
+    ).toThrow(/dependency cycle among roots: a, b/);
+  });
+
+  test("a dependency outside the rollout orders nothing", () => {
+    expect(planPinWaves([{ root: "a", dependsOn: ["elsewhere"] }])).toEqual([{ wave: 1, canary: false, roots: ["a"] }]);
+  });
+});
+
+describe("wavesFromChoudoufu", () => {
+  // `choudoufu live-waves -json -canary=estates/e04` over choudoufu#1750's N=5 fixture, recorded from choudoufu main.
+  const doc = JSON.parse(readFileSync(new URL("../__fixtures__/pin/choudoufu-live-waves-n5.json", import.meta.url), "utf-8"));
+
+  test("takes each wave's root list as choudoufu's planner emits it", () => {
+    expect(wavesFromChoudoufu(doc)).toEqual([
+      { wave: 1, canary: true, roots: ["estates/e04"] },
+      { wave: 2, canary: false, roots: ["estates/e01", "estates/e05"] },
+      { wave: 3, canary: false, roots: ["estates/e02"] },
+      { wave: 4, canary: false, roots: ["estates/e03"] },
+    ]);
+  });
+
+  test("agrees with the declared-order planner on the same graph", () => {
+    expect(wavesFromChoudoufu(doc)).toEqual(planPinWaves(N5, ["estates/e04"]));
+  });
+
+  test("a prefix places the roots under the directory choudoufu ran in", () => {
+    expect(wavesFromChoudoufu(doc, "infra")[0]!.roots).toEqual(["infra/estates/e04"]);
+  });
+
+  test("refuses another format", () => {
+    expect(() => wavesFromChoudoufu({ format_version: "2", waves: [] })).toThrow(/format version 1/);
+  });
+
+  test("restrictWaves drops roots not moving and renumbers", () => {
+    expect(restrictWaves(wavesFromChoudoufu(doc), new Set(["estates/e02", "estates/e05"]))).toEqual([
+      { wave: 1, canary: false, roots: ["estates/e05"] },
+      { wave: 2, canary: false, roots: ["estates/e02"] },
+    ]);
+  });
+});
+
+describe("terragruntDependencies", () => {
+  test("reads dependency config_path and dependencies paths, relative to the unit", async () => {
+    const parser = await loadHcl2json();
+    const text = [
+      `dependency "vpc" {`,
+      `  config_path = "../vpc"`,
+      `  mock_outputs = { id = "x" }`,
+      `}`,
+      `dependencies {`,
+      `  paths = ["../dns", "\${get_repo_root()}/x"]`,
+      `}`,
+    ].join("\n");
+    expect(await terragruntDependencies("live/prod/app", text, parser)).toEqual(["live/prod/dns", "live/prod/vpc"]);
+  });
+});