@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/src/pin/waves.ts

@@ -0,0 +1,125 @@
+/**
+ * The wave plan for a pin-bump rollout (#3189): which roots move in which PR.
+ *
+ * Two sources give the same shape, an ordered list of root lists:
+ *
+ * - **Declared canaries, then dependency order.** The canaries form wave 1.
+ *   Every other root lands in the earliest wave after every root it depends
+ *   on. That is the Kahn layering `chant components fan-out` uses
+ *   (`resolveComponentGraph`, `@intentius/chant/components/layers`), and the
+ *   order #3049 gives its gated waves. A canary that depends on a root outside
+ *   the canaries is refused, since wave 1 would apply before what it reads.
+ * - **choudoufu's wave planner** (`choudoufu live-waves -json`, choudoufu#1754).
+ *   It reads cross-estate references from the estates' own configuration, puts
+ *   `-canary` roots in wave 1, and emits each wave's roots on their own, so
+ *   {@link wavesFromChoudoufu} takes its document as it is.
+ *
+ * A root's dependencies come from the caller (`dependsOn`) and, for a
+ * Terragrunt unit, from its `dependency` and `dependencies` blocks
+ * ({@link terragruntDependencies}). A dependency on a root outside the
+ * rollout orders nothing: it is not moving.
+ */
+
+import { posix } from "node:path";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { kahnLayers } from "@intentius/chant/components/layers";
+
+/** One root in a rollout. `root` is its directory, relative to the repository, with `/` separators. */
+export interface PinRoot {
+  root: string;
+  /** Roots this one reads, by directory. They land in an earlier wave. */
+  dependsOn?: string[];
+  /**
+   * The TypeScript file a generated root is built from. The pin edit then
+   * goes to the module declaration there rather than to the `.tf` chant
+   * writes (`./edit-ts.ts`).
+   */
+  tsSource?: string;
+}
+
+/** One wave: its number from 1, whether the declared canaries form it, and its roots, sorted. */
+export interface PinWave {
+  wave: number;
+  canary: boolean;
+  roots: string[];
+}
+
+/** Thrown when the roots cannot be split into waves. The message names the roots. */
+export class PinWavePlanError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PinWavePlanError";
+  }
+}
+
+/** Canaries first, then dependency order. */
+export function planPinWaves(roots: readonly PinRoot[], canaries: readonly string[] = []): PinWave[] {
+  const names = new Set(roots.map((r) => r.root));
+  for (const c of canaries) {
+    if (!names.has(c)) throw new PinWavePlanError(`canary ${c} is not a root of this rollout (roots: ${[...names].sort().join(", ") || "none"})`);
+  }
+  const canarySet = new Set(canaries);
+  const deps = new Map<string, Set<string>>();
+  for (const r of roots) deps.set(r.root, new Set((r.dependsOn ?? []).filter((d) => names.has(d) && d !== r.root)));
+
+  for (const c of canarySet) {
+    const outside = [...deps.get(c)!].filter((d) => !canarySet.has(d));
+    if (outside.length > 0) throw new PinWavePlanError(`canary ${c} depends on ${outside.join(", ")}, which is not a canary, so wave 1 would move it first`);
+  }
+
+  const waves: PinWave[] = [];
+  if (canarySet.size > 0) waves.push({ wave: 1, canary: true, roots: [...canarySet].sort() });
+  const rest = new Map([...deps].filter(([n]) => !canarySet.has(n)).map(([n, d]) => [n, new Set([...d].filter((x) => !canarySet.has(x)))]));
+  const layered = kahnLayers(rest);
+  if (layered.cycle) throw new PinWavePlanError(`dependency cycle among roots: ${layered.cycle.join(", ")}`);
+  for (const roots of layered.waves) waves.push({ wave: waves.length + 1, canary: false, roots });
+  return waves;
+}
+
+/**
+ * The waves of a `choudoufu live-waves -json` document (format version 1).
+ * `prefix` is the directory choudoufu ran in, relative to the repository,
+ * when its roots are named relative to that rather than to the repository.
+ */
+export function wavesFromChoudoufu(doc: unknown, prefix = ""): PinWave[] {
+  const d = doc as { format_version?: unknown; waves?: unknown };
+  if (d?.format_version !== "1") throw new PinWavePlanError(`not a choudoufu live-waves document of format version 1 (format_version: ${JSON.stringify(d?.format_version)})`);
+  if (!Array.isArray(d.waves)) throw new PinWavePlanError("the live-waves document has no waves");
+  return d.waves.map((w: { wave?: unknown; canary?: unknown; roots?: unknown }, i) => {
+    if (w.wave !== i + 1 || !Array.isArray(w.roots) || w.roots.some((r) => typeof r !== "string")) {
+      throw new PinWavePlanError(`live-waves wave ${i + 1} is malformed`);
+    }
+    return { wave: i + 1, canary: w.canary === true, roots: (w.roots as string[]).map((r) => (prefix ? posix.join(prefix, r) : posix.normalize(r))).sort() };
+  });
+}
+
+/**
+ * Keep only the roots in `keep`, renumbering the waves and dropping any left
+ * empty. A wave plan from choudoufu covers every root it was given; the
+ * rollout moves only the roots that call the module at the old or new pin.
+ */
+export function restrictWaves(waves: readonly PinWave[], keep: ReadonlySet<string>): PinWave[] {
+  const out: PinWave[] = [];
+  for (const w of waves) {
+    const roots = w.roots.filter((r) => keep.has(r));
+    if (roots.length > 0) out.push({ wave: out.length + 1, canary: w.canary, roots });
+  }
+  return out;
+}
+
+/**
+ * The roots a Terragrunt unit depends on: each `dependency` block's
+ * `config_path` and the `dependencies` block's `paths`, resolved against the
+ * unit's directory. A path that is an expression is skipped, since it names
+ * no directory until Terragrunt evaluates it.
+ */
+export async function terragruntDependencies(root: string, text: string, parser: Hcl2Json): Promise<string[]> {
+  const tree = (await parser.parse(posix.join(root, "terragrunt.hcl"), text)) as {
+    dependency?: Record<string, Array<{ config_path?: unknown }>>;
+    dependencies?: Array<{ paths?: unknown }>;
+  };
+  const paths: string[] = [];
+  for (const blocks of Object.values(tree.dependency ?? {})) for (const b of blocks) if (typeof b.config_path === "string") paths.push(b.config_path);
+  for (const b of tree.dependencies ?? []) if (Array.isArray(b.paths)) for (const p of b.paths) if (typeof p === "string") paths.push(p);
+  return [...new Set(paths.filter((p) => !p.includes("${")).map((p) => posix.normalize(posix.join(root, p))))].sort();
+}

package/src/plan-digest.ts

@@ -0,0 +1,99 @@
+/**
+ * A terraform plan's identity (#2300), kept apart from the activities so the
+ * change-set adapter (`../change-set.ts`, #3181) can import it without the
+ * config loader, the HCL parse or anything else the activities reach. It
+ * imports chant's `lifecycle/plan-digest` subpath and nothing more, which is
+ * what lets terragucci bundle it into one file (#3421).
+ */
+
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+
+/**
+ * One resource's proposed change, as a plan digest sees it (#2300) — the
+ * projection of a `terraform show -json` `resource_changes` entry that
+ * survives into {@link terraformPlanDigest}.
+ */
+export interface TerraformPlannedChange {
+  address: unknown;
+  mode: unknown;
+  type: unknown;
+  name: unknown;
+  index: unknown;
+  provider_name: unknown;
+  deposed: unknown;
+  actions: unknown;
+  before: unknown;
+  after: unknown;
+  after_unknown: unknown;
+  replace_paths: unknown;
+  importing: unknown;
+}
+
+/**
+ * The change set a `terraform show -json` plan describes, canonicalised
+ * (#2300): every proposed change, at its address, with the values that would
+ * be written, sorted so two renderings of the same plan project identically.
+ *
+ * Everything else in the document is dropped, and the drops are the point —
+ * see `packages/core/src/lifecycle/plan-digest.ts` for the general rule. Here
+ * that means `timestamp` and `terraform_version` (when the plan was taken and
+ * by which binary), `format_version` (how it was rendered), `prior_state` and
+ * `planned_values` (restatements of the same change set from another angle),
+ * `configuration` (the source that produced it, which can be refactored
+ * without changing a single proposed action) and `checks` / `relevant_
+ * attributes` (diagnostics about the plan, not the plan). What is left is
+ * what applying it would do.
+ */
+export function terraformPlanChangeSet(planJson: unknown): {
+  resourceChanges: TerraformPlannedChange[];
+  outputChanges: unknown;
+  actionInvocations?: unknown[];
+} {
+  const doc = planJson as { resource_changes?: unknown; output_changes?: unknown; action_invocations?: unknown } | null | undefined;
+  const raw = Array.isArray(doc?.resource_changes) ? doc.resource_changes : [];
+  const resourceChanges = raw.map((entry): TerraformPlannedChange => {
+    const e = (entry ?? {}) as Record<string, unknown>;
+    const change = (e.change ?? {}) as Record<string, unknown>;
+    return {
+      address: e.address,
+      mode: e.mode,
+      type: e.type,
+      name: e.name,
+      index: e.index,
+      provider_name: e.provider_name,
+      deposed: e.deposed,
+      actions: change.actions,
+      before: change.before,
+      after: change.after,
+      after_unknown: change.after_unknown,
+      replace_paths: change.replace_paths,
+      importing: change.importing,
+    };
+  });
+  // terraform already emits these in address order, but nothing in the format
+  // promises it, and a digest that depends on the emitter's iteration order
+  // would refuse a plan that is identical in every way that matters.
+  resourceChanges.sort((a, b) =>
+    `${String(a.address)}\u0000${String(a.deposed ?? "")}`.localeCompare(
+      `${String(b.address)}\u0000${String(b.deposed ?? "")}`,
+    ),
+  );
+  // Terraform 1.14 `action` blocks: side effects an apply runs. Present only
+  // when the plan has some, so the digest of a plan without them is unchanged.
+  const invocations = Array.isArray(doc?.action_invocations) ? [...doc.action_invocations].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) : [];
+  return { resourceChanges, outputChanges: doc?.output_changes ?? {}, ...(invocations.length > 0 ? { actionInvocations: invocations } : {}) };
+}
+
+/**
+ * The identity of a terraform plan (#2300): {@link terraformPlanChangeSet}
+ * hashed. This is what a `TerraformApplyOp` gate binds its approval to, and
+ * what a later run recomputes and compares.
+ *
+ * Taken over the `show -json` rendering rather than the plan file's bytes on
+ * purpose: the file is an opaque, version-stamped archive, and two runs of
+ * `plan -out` over an unchanged root produce different bytes. The rendering
+ * is the same plan both times.
+ */
+export function terraformPlanDigest(planJson: unknown): string {
+  return computePlanDigest("terraform-plan", terraformPlanChangeSet(planJson));
+}

package/src/plan-summary.test.ts

@@ -0,0 +1,154 @@
+/**
+ * The grouped plan summary (#3188) over terraform-family change sets.
+ *
+ * `packages/core/src/__fixtures__/plan-summary/normalization-vectors.json`
+ * is the rule table chant and choudoufu both run (the ruling on #3188 and
+ * choudoufu#1753). Its root pairs are choudoufu set-plan roots, read here
+ * through `choudoufuSetPlanParts` exactly as a real set plan is; its
+ * instance pairs are two `resource_changes` of one plan. The table is proved
+ * red two ways: a grouper that compares raw changes fails every must-group
+ * row, and one that blanks every string fails the must-not rows the file
+ * names.
+ *
+ * `__fixtures__/plan-summary/largeset-n5-bump.json` is choudoufu's real set
+ * plan of choudoufu#1750's module bump at N=5 against floci
+ * (`internal/live/plansummary/testdata/largeset-n5-bump.json`, choudoufu
+ * 8f08b6cbb7). e04 is the planted outlier. Goldens regenerate with
+ * `UPDATE_GOLDEN=1`; `packages/core/src/plan-summary.test.ts` validates the
+ * JSON one against the schema.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { composeChangeSet } from "@intentius/chant/change-set";
+import { groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "@intentius/chant/plan-summary";
+import { choudoufuSetPlanParts, terraformChangeSetPart } from "./change-set";
+
+const DIR = join(import.meta.dirname, "__fixtures__", "plan-summary");
+const VECTORS = join(import.meta.dirname, "..", "..", "..", "packages", "core", "src", "__fixtures__", "plan-summary", "normalization-vectors.json");
+
+function golden(name: string, text: string): void {
+  const path = join(DIR, name);
+  if (process.env.UPDATE_GOLDEN) writeFileSync(path, text);
+  expect(text).toBe(readFileSync(path, "utf-8"));
+}
+
+type Json = Record<string, any>;
+
+interface Pair {
+  name: string;
+  group: boolean;
+  a: Json;
+  b: Json;
+}
+
+const vectors = JSON.parse(readFileSync(VECTORS, "utf-8")) as {
+  format: string;
+  rootPairs: Pair[];
+  instancePairs: Pair[];
+  overEagerFalselyGroups: string[];
+};
+
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
+
+/** Whether the summary puts two roots of one set plan in one group. */
+function rootsGroup(a: Json, b: Json): boolean {
+  const doc = composeChangeSet(choudoufuSetPlanParts({ document: { roots: [a, b] } }));
+  const s = groupChangeSet(doc);
+  return s.failed.length === 0 && s.groups.length === 1;
+}
+
+/** Whether the summary puts two instances of one plan in one group. */
+function instancesGroup(a: Json, b: Json): boolean {
+  const doc = composeChangeSet([terraformChangeSetPart({ member: "root", plan: { format_version: "1.2", resource_changes: [a, b] } })]);
+  return groupChangeSet(doc).groups.length === 1;
+}
+
+/** Grouping by the raw change set: equal bytes or nothing. */
+const naiveRootsGroup = (a: Json, b: Json): boolean => JSON.stringify(a.plan.resource_changes) === JSON.stringify(b.plan.resource_changes);
+
+/** The normalizer this must not be: every string in before and after blanked first. */
+function blankStrings(root: Json): Json {
+  const blank = (v: unknown): unknown =>
+    typeof v === "string" ? "x" : Array.isArray(v) ? v.map(blank) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, e]) => [k, blank(e)])) : v;
+  const r = clone(root);
+  for (const rc of r.plan.resource_changes) {
+    if (rc.change.before) rc.change.before = blank(rc.change.before);
+    if (rc.change.after) rc.change.after = blank(rc.change.after);
+  }
+  return r;
+}
+
+describe("the shared normalization vectors", () => {
+  test("are the format this test reads, with both kinds of pair", () => {
+    expect(vectors.format).toBe("plan-summary-normalization-vectors/1");
+    for (const rows of [vectors.rootPairs, vectors.instancePairs]) {
+      expect(rows.some((r) => r.group)).toBe(true);
+      expect(rows.some((r) => !r.group)).toBe(true);
+    }
+  });
+
+  test.each(vectors.rootPairs.map((r) => [r.name, r] as const))("roots: %s", (_, row) => {
+    expect(rootsGroup(row.a, row.b)).toBe(row.group);
+  });
+
+  test.each(vectors.instancePairs.map((r) => [r.name, r] as const))("instances: %s", (_, row) => {
+    expect(instancesGroup(row.a, row.b)).toBe(row.group);
+  });
+
+  test("red first: a raw hash keeps every must-group pair apart", () => {
+    const grouped = vectors.rootPairs.filter((r) => r.group && naiveRootsGroup(r.a, r.b)).map((r) => r.name);
+    expect(grouped).toEqual([]);
+  });
+
+  test("red first: blanking every string falsely groups exactly the named must-not pairs", () => {
+    const falselyGrouped = vectors.rootPairs.filter((r) => !r.group && rootsGroup(blankStrings(r.a), blankStrings(r.b))).map((r) => r.name);
+    expect(falselyGrouped.sort()).toEqual([...vectors.overEagerFalselyGroups].sort());
+  });
+});
+
+describe("choudoufu#1750's module bump at N=5", () => {
+  const document = JSON.parse(readFileSync(join(DIR, "largeset-n5-bump.json"), "utf-8")) as Json;
+  const doc = composeChangeSet(choudoufuSetPlanParts({ document }));
+  const summary = groupChangeSet(doc);
+
+  test("is one group plus the planted outlier, which reads as the group's change plus its extra queue", () => {
+    expect(summary.groups.map((g) => g.units)).toEqual([["estates/e01", "estates/e02", "estates/e03", "estates/e05"], ["estates/e04"]]);
+    const [base, outlier] = summary.groups;
+    expect(outlier.outlier).toBe(true);
+    expect(outlier.extends).toBe(base.id);
+    expect(outlier.plus?.map((l) => l.line)).toEqual(["~ module.shared.aws_sqs_queue.extra: tags, tags_all"]);
+    expect(summary.destroys).toEqual([]);
+    expect(summary.failed).toEqual([]);
+  });
+
+  test("keeps its group ids when the same change is planned again", () => {
+    const again = groupChangeSet(composeChangeSet(choudoufuSetPlanParts({ document: clone(document) }).reverse()));
+    expect(again.groups.map((g) => g.id)).toEqual(summary.groups.map((g) => g.id));
+  });
+
+  test("renders its goldens", () => {
+    golden("largeset-n5.summary.golden.json", JSON.stringify(summary, null, 2) + "\n");
+    golden("largeset-n5.summary.golden.txt", renderPlanSummaryText(summary));
+    golden("largeset-n5.summary.golden.md", renderPlanSummaryMarkdown(summary));
+  });
+});
+
+describe("one root's for_each expansion", () => {
+  test("groups instances whose changes differ only in their own key, and names each destroy", () => {
+    const changes = ["a", "b", "c"].map((k) => ({
+      address: `aws_s3_bucket.logs["${k}"]`,
+      change: { actions: ["update"], before: { bucket: `logs-${k}`, tags: { Name: `logs-${k}`, v: "1" } }, after: { bucket: `logs-${k}`, tags: { Name: `logs-${k}`, v: "2" } } },
+    }));
+    changes.push({ address: 'aws_s3_bucket.logs["d"]', change: { actions: ["delete", "create"], before: { bucket: "logs-d", tags: { Name: "logs-d", v: "1" } }, after: { bucket: "logs-d2", tags: { Name: "logs-d", v: "2" } } } });
+    const doc = composeChangeSet([terraformChangeSetPart({ member: "root", plan: { format_version: "1.2", resource_changes: changes } })]);
+    const s = groupChangeSet(doc);
+    expect(s.unit).toBe("instance");
+    expect(s.groups.map((g) => [g.resource, g.units])).toEqual([
+      ["aws_s3_bucket.logs", ['aws_s3_bucket.logs["a"]', 'aws_s3_bucket.logs["b"]', 'aws_s3_bucket.logs["c"]']],
+      ["aws_s3_bucket.logs", ['aws_s3_bucket.logs["d"]']],
+    ]);
+    expect(s.destroys).toEqual([{ member: "root", address: 'aws_s3_bucket.logs["d"]', type: "aws_s3_bucket", action: "replace" }]);
+  });
+});

package/src/plugin.ts

@@ -12,9 +12,12 @@ import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { terraformConfigSchema, type TerraformConfig } from "./config";
 import { renderTerraformRoots } from "./hcl/roots";
-import { auditRootName, parseTerraformRootContent, RESOURCE_TYPE } from "./hcl/parse";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { auditRootName, LOCK_FILENAME, parseTerraformRootContent, RESOURCE_TYPE } from "./hcl/parse";
 import { descendModules } from "./hcl/descend";
 import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership";
+import { terraformCommands } from "./commands";
 
 const loadSkills = createSkillsLoader(import.meta.url, [
   {
@@ -187,6 +190,23 @@ export const terraformPlugin: LexiconPlugin = {
     });
   },
 
+  /** `chant terraform pin-rollout` (#3189). */
+  commands() {
+    return terraformCommands;
+  },
+
+  /**
+   * The `terraform.roots` a change touched (#3183): a changed file in the
+   * root's directory, in a local module it calls, or one of its var files.
+   * See `./changed-roots.ts`.
+   */
+  async changedUnits(ctx) {
+    const roots = (ctx.config as { terraform?: TerraformConfig }).terraform?.roots ?? {};
+    if (Object.keys(roots).length === 0) return [];
+    const { changedRoots } = await import("./changed-roots");
+    return changedRoots(ctx.projectRoot, roots, ctx.changedFiles);
+  },
+
   lintRules() {
     return rules;
   },
@@ -256,7 +276,10 @@ export const terraformPlugin: LexiconPlugin = {
   async auditEntities(content: string, input?: AuditEntitiesInput): Promise<Map<string, Declarable>> {
     try {
       const root = auditRootName(input?.path);
-      const entities = await parseTerraformRootContent(content, root);
+      // A local audit knows the root's directory, so it can say whether the
+      // lock file is beside the `.tf` files (TF040); a fetched one cannot.
+      const lockFile = input?.dir !== undefined ? existsSync(join(input.dir, LOCK_FILENAME)) : undefined;
+      const entities = await parseTerraformRootContent(content, root, undefined, lockFile === undefined ? undefined : { lockFile });
       if (input?.dir === undefined) return entities;
       const { entities: children } = await descendModules(entities, {
         dir: input.dir,

package/src/terragrunt/affected.acceptance.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Affected Terragrunt units (#3415) against a real `terragrunt` 1.1+ and
+ * `git`: each case of `../__fixtures__/terragrunt/affected-cases.ts` is made
+ * as a commit on a copy of the `affected/` fixture. Terragrunt's own
+ * `[HEAD~1...HEAD]` filter must select exactly the case's `terragrunt`
+ * column (for the three supplements, nothing: the red half), and
+ * `findTerragruntAffected` must return the case's expected units and reasons.
+ *
+ * Nothing is planned, so `tofu` is not needed. Skipped, with the reason in
+ * the title, when `terragrunt` or `git` is not on PATH.
+ */
+
+import { execFileSync, execSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import { AFFECTED_CASES } from "../__fixtures__/terragrunt/affected-cases";
+import { defaultTerragruntExec, discoverTerragruntUnits, findTerragruntAffected, parseTerragruntFind, terragruntAffectedFindArgs } from "./index";
+
+function onPath(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const skipReason = !onPath("terragrunt") ? "no terragrunt on PATH" : !onPath("git") ? "no git on PATH" : "";
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "../__fixtures__/terragrunt");
+const tmp = mkdtempSync(join(tmpdir(), "chant-tg-affected-accept-"));
+afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+const gitEnv = { ...process.env, GIT_AUTHOR_NAME: "chant", GIT_AUTHOR_EMAIL: "chant@example.com", GIT_COMMITTER_NAME: "chant", GIT_COMMITTER_EMAIL: "chant@example.com" };
+const git = (dir: string, ...args: string[]): string => execFileSync("git", args, { cwd: dir, env: gitEnv, encoding: "utf8" });
+const generate = (dir: string): void => {
+  execFileSync("terragrunt", ["stack", "generate", "--no-color"], { cwd: dir, stdio: "ignore" });
+};
+
+/** A copy of the fixture as a git repository at its base commit, stacks generated. */
+function baseRepo(name: string): string {
+  const dir = join(tmp, name.replace(/[^a-z0-9]+/gi, "-"));
+  cpSync(join(fixtures, "affected"), dir, { recursive: true });
+  renameSync(join(dir, "gitignore"), join(dir, ".gitignore"));
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "add", "-A");
+  git(dir, "commit", "-q", "-m", "base");
+  generate(dir);
+  return dir;
+}
+
+describe.skipIf(skipReason !== "")(`affected Terragrunt units against a real terragrunt${skipReason ? ` (skipped: ${skipReason})` : ""}`, () => {
+  it("discovers what recorded/affected-find.json holds", async () => {
+    const dir = baseRepo("discovery");
+    const { units } = await discoverTerragruntUnits({ dir });
+    expect(units).toEqual(parseTerragruntFind(readFileSync(join(fixtures, "recorded/affected-find.json"), "utf8")));
+  });
+
+  for (const c of AFFECTED_CASES) {
+    it(
+      c.name,
+      async () => {
+        const dir = baseRepo(c.name);
+        c.change(dir);
+        git(dir, "add", "-A");
+        git(dir, "commit", "-q", "-m", c.name);
+        generate(dir);
+        expect(git(dir, "diff", "--name-only", "HEAD~1...HEAD").trim().split("\n").sort()).toEqual([...c.changed].sort());
+
+        const own = await defaultTerragruntExec("terragrunt", terragruntAffectedFindArgs({ base: "HEAD~1" }), { cwd: dir, env: {} });
+        expect(own.code, own.stderr).toBe(0);
+        expect(parseTerragruntFind(own.stdout).map((u) => u.path).sort()).toEqual(c.terragrunt);
+
+        const got = await findTerragruntAffected({ dir, base: "HEAD~1" });
+        expect(got.units).toEqual(c.expected);
+        expect(got.notes).toEqual([]);
+      },
+      60_000,
+    );
+  }
+});