@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/pin/consumers.js

@@ -0,0 +1,70 @@
+/**
+ * Where a repo calls its modules (chant#4599, terragucci#1289 bundle B): one
+ * entry per module call in the roots given, Terragrunt units included, read
+ * from the source files with chant's HCL parse and never from a plan, so the
+ * scan runs in a check job before anything is planned.
+ *
+ * Each call carries its root, file and block path, the source as written,
+ * the module it names with the pin taken out and normalised
+ * ({@link normalizeModuleSource}), and the pin `readModulePin` (./source.ts)
+ * reads. A local call (`./`, `../`) names no published module and is left
+ * out. The release catalog lists these as a version's consumers, and
+ * `deprecatedPins` (../registry/deprecated.ts) checks them against it.
+ *
+ * The `terragucci_module_pin` metric keeps reading the plan; this is the
+ * source-side view of the same calls. The normal form is chant#3924's
+ * (../registry/source-forms.ts), shared with `usedSources` (../sources.ts).
+ */
+import { join, relative } from "node:path";
+import { MODULE_TYPE, TERRAGRUNT_SOURCE_TYPE, parseTerraformRootDir } from "../hcl/parse.js";
+import { normalizeModuleSource, PUBLIC_REGISTRY_HOST } from "../registry/source-forms.js";
+import { readModulePin } from "./source.js";
+export { normalizeModuleSource, PUBLIC_REGISTRY_HOST };
+/** A source names a local directory, not a published module. */
+export function isLocalSource(source) {
+    return source.startsWith("./") || source.startsWith("../");
+}
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Every module call in `roots` (directories from `repo`), sorted by root,
+ * file and address. A root whose files cannot be parsed throws, naming the
+ * root, so a check job fails loudly instead of listing fewer consumers.
+ */
+export async function moduleConsumers(repo, roots, parser) {
+    const out = [];
+    for (const root of [...new Set(roots)].sort()) {
+        const dir = join(repo, root);
+        const rel = relative(repo, dir).split("\\").join("/") || ".";
+        let entities;
+        try {
+            entities = [...(await parseTerraformRootDir(dir, "consumers", parser)).values()];
+        }
+        catch (e) {
+            throw new Error(`${rel}: ${e.message}`);
+        }
+        for (const e of entities) {
+            if (e.entityType !== MODULE_TYPE && e.entityType !== TERRAGRUNT_SOURCE_TYPE)
+                continue;
+            const source = str(e.props.body.source);
+            if (source === undefined || isLocalSource(source))
+                continue;
+            const version = e.entityType === MODULE_TYPE ? str(e.props.body.version) : undefined;
+            const pin = readModulePin(source, version);
+            out.push({
+                root: rel,
+                file: rel === "." ? e.props.file : `${rel}/${e.props.file}`,
+                address: e.props.address,
+                kind: e.entityType === MODULE_TYPE ? "terraform" : "terragrunt",
+                source,
+                module: normalizeModuleSource(pin.module),
+                pin: pin.pin,
+                at: pin.at,
+                ...(pin.param ? { param: pin.param } : {}),
+                ...(pin.unpinned ? { unpinned: pin.unpinned } : {}),
+            });
+        }
+    }
+    return out.sort((a, b) => a.root.localeCompare(b.root) || a.file.localeCompare(b.file) || a.address.localeCompare(b.address));
+}

package/dist/pin/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/pin/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAGjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IACpC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AA2CD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAgDxH"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/pin/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAIjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IACpC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AA2CD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAiDxH"}

package/dist/pin/edit.js

@@ -22,6 +22,7 @@
  * module (terragucci's `tf-rollout` stage, #3421) decides how it is loaded.
  */
 import { movePin } from "./source.js";
+import { isJsonConfigFile, jsonConfigTree } from "../hcl/files.js";
 import { escapeHcl, scanBlocks, unescapeHcl } from "./scan.js";
 /** Whether a file is read as a Terragrunt configuration rather than a `.tf` file. */
 export function isTerragruntFile(file) {
@@ -58,6 +59,8 @@ function sites(tree, blocks, terragrunt) {
  * is reported with its reason and left as it was.
  */
 export async function editPins(text, file, request, parser) {
+    if (isJsonConfigFile(file))
+        return jsonPins(text, file, request);
     const terragrunt = isTerragruntFile(file);
     const tree = (await parser.parse(file, text));
     const blocks = scanBlocks(text, file);
@@ -116,3 +119,35 @@ export async function editPins(text, file, request, parser) {
 function rewriteLiteral(raw, was, value) {
     return raw === was ? value : escapeHcl(value);
 }
+/**
+ * The calls of the module in a `.tf.json` or `.tofu.json` file (chant#4457).
+ * The pin edit splices HCL text and has no splice for JSON syntax, so a call
+ * that would move is refused by name and the file is left as it is; a call
+ * already at the new pin, or at another one, reads as it does in HCL.
+ */
+function jsonPins(text, file, request) {
+    const calls = [];
+    let tree;
+    try {
+        tree = jsonConfigTree(text);
+    }
+    catch (err) {
+        return { content: text, calls: [{ outcome: "refused", reason: `not JSON the binary reads: ${err instanceof Error ? err.message : String(err)}`, file, call: "(file)" }] };
+    }
+    const modules = (tree.module && typeof tree.module === "object" ? tree.module : {});
+    for (const [name, bodies] of Object.entries(modules)) {
+        for (const body of Array.isArray(bodies) ? bodies : []) {
+            if (typeof body.source !== "string")
+                continue;
+            const move = movePin(body.source, typeof body.version === "string" ? body.version : undefined, request);
+            if (!move)
+                continue;
+            const at = { file, call: `module.${name}` };
+            if (move.outcome === "moved")
+                calls.push({ outcome: "refused", reason: "the call is in Terraform's JSON syntax, which the pin edit does not write; move its pin by hand", ...at });
+            else
+                calls.push({ ...move, ...at });
+        }
+    }
+    return { content: text, calls };
+}

package/dist/pin/rollout.d.ts

@@ -70,6 +70,8 @@ export interface PinRolloutOptions extends PinRequest {
     editTs?: TsPinEditor;
     /** Markdown appended to a wave's PR body, such as the grouped plan summary of #3188 once a caller has the wave's plans. */
     planSummary?: (wave: PinWave) => Promise<string | undefined>;
+    /** The binary the roots run: `tofu` or `choudoufu` reads `.tofu` files too (chant#4457). Default `terraform`. */
+    binary?: string;
 }
 /** Where one root's pin stood on the base branch. */
 export interface PinRootState {

package/dist/pin/rollout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rollout.d.ts","sourceRoot":"","sources":["../../src/pin/rollout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rollout.d.ts","sourceRoot":"","sources":["../../src/pin/rollout.ts"],"names":[],"mappings":"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"}

package/dist/pin/rollout.js

@@ -45,6 +45,7 @@ import { editPins } from "./edit.js";
 import { checkPinRequest, moduleOf } from "./source.js";
 import { planPinWaves, restrictWaves, terragruntDependencies } from "./waves.js";
 import { ghPinForge } from "./forge.js";
+import { isConfigFileFor, listConfigFilesSafe } from "../hcl/files.js";
 const execFileAsync = /* @__PURE__ */ promisify(execFile);
 // `gh pr list/create` and `gh api repos/{owner}/{repo}/...` name no host, so
 // a `gh` call is told the job's forge or `origin`'s host (core's `ghHostEnv`,
@@ -73,22 +74,24 @@ function slug(value) {
 export function pinWaveBranch(request, wave) {
     return `chant/pin/${slug(request.module)}/${slug(request.to)}/wave-${wave}`;
 }
-/** The files the pin edit reads in a root directory: its `.tf` files and its `terragrunt.hcl`. */
-function rootFiles(worktree, root) {
+/**
+ * The files the pin edit reads in a root directory: the configuration files
+ * the root's binary reads (the lexicon's one lister, chant#4457) and its
+ * `terragrunt.hcl`.
+ */
+function rootFiles(worktree, root, binary) {
     const dir = join(worktree, root);
     if (!existsSync(dir))
         return [];
-    return readdirSync(dir)
-        .filter((f) => f.endsWith(".tf") || f === "terragrunt.hcl")
-        .sort()
-        .map((f) => posix.join(root, f));
+    const names = [...listConfigFilesSafe(dir, binary), ...(existsSync(join(dir, "terragrunt.hcl")) ? ["terragrunt.hcl"] : [])];
+    return names.sort().map((f) => posix.join(root, f));
 }
-/** Every directory under the worktree with a `.tf` file or a `terragrunt.hcl`. */
-function candidateRoots(worktree) {
+/** Every directory under the worktree with a configuration file the binary reads, or a `terragrunt.hcl`. */
+function candidateRoots(worktree, binary) {
     const out = [];
     const walk = (rel) => {
         const entries = readdirSync(join(worktree, rel), { withFileTypes: true });
-        if (entries.some((e) => e.isFile() && (e.name.endsWith(".tf") || e.name === "terragrunt.hcl")))
+        if (entries.some((e) => e.isFile() && (isConfigFileFor(e.name, binary) || e.name === "terragrunt.hcl")))
             out.push(rel || ".");
         for (const e of entries)
             if (e.isDirectory() && !SKIP_DIRS.has(e.name))
@@ -108,7 +111,7 @@ async function editRoot(worktree, root, request, options) {
         }
     }
     else {
-        files = rootFiles(worktree, root.root);
+        files = rootFiles(worktree, root.root, options.binary);
     }
     for (const file of files) {
         const path = join(worktree, file);
@@ -216,7 +219,7 @@ export async function runPinRollout(options) {
     await run("git", ["worktree", "add", "--quiet", "--detach", worktree, baseRef], repo);
     try {
         // 1. Every root's pin on the base branch.
-        const declared = (options.roots ?? candidateRoots(worktree).map((root) => ({ root }))).map((r) => ({
+        const declared = (options.roots ?? candidateRoots(worktree, options.binary).map((root) => ({ root }))).map((r) => ({
             ...r,
             root: dirOf(r.root),
             ...(r.dependsOn ? { dependsOn: r.dependsOn.map(dirOf) } : {}),

package/dist/plan-shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The plan shape of a terraform-family root (#4436): what `terraform show
+ * -json` says a plan does, without the values, in the form core's
+ * `coveredRound` compares (#4419). `terraform-apply`'s `plan` returns it, and
+ * terragucci calls it for the plan JSON of a note (terragucci#1268).
+ *
+ * Like `./change-set`, this module imports only `@intentius/chant` subpaths,
+ * never the lexicon's entry point.
+ */
+import type { PlanShape } from "@intentius/chant/components/covered-round";
+export interface TerraformPlanShapeOptions {
+    /** The inputs the plan was made without, as `<component>.<output>`. */
+    unknownInputs?: string[];
+    /** The inputs the plan read with a value, by reference. */
+    knownInputs?: Record<string, unknown>;
+}
+/**
+ * The shape of `planJson` (`terraform show -json`, from terraform, tofu or
+ * choudoufu) for `member`.
+ *
+ * One entry per `resource_changes` item that is not `no-op` or `read`.
+ * `logicalId` is the address, with `#<deposed>` for a deposed object. `type`
+ * is the resource type. `properties` are the top-level attributes that differ
+ * between `before` and `after` (on a create, those the plan sets or leaves
+ * unknown), and `unknown` the ones `after_unknown` marks, so `unknown` is
+ * within `properties`. A delete has no properties. Values never enter it, so
+ * a sensitive attribute is only a name.
+ */
+export declare function terraformPlanShape(planJson: unknown, member: string, options?: TerraformPlanShapeOptions): PlanShape;
+//# sourceMappingURL=plan-shape.d.ts.map

package/dist/plan-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-shape.d.ts","sourceRoot":"","sources":["../src/plan-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoC,MAAM,2CAA2C,CAAC;AAuD7G,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B,GAAG,SAAS,CA2CxH"}

package/dist/plan-shape.js

@@ -0,0 +1,125 @@
+/**
+ * The plan shape of a terraform-family root (#4436): what `terraform show
+ * -json` says a plan does, without the values, in the form core's
+ * `coveredRound` compares (#4419). `terraform-apply`'s `plan` returns it, and
+ * terragucci calls it for the plan JSON of a note (terragucci#1268).
+ *
+ * Like `./change-set`, this module imports only `@intentius/chant` subpaths,
+ * never the lexicon's entry point.
+ */
+import { normalizePlanShape } from "@intentius/chant/components/covered-round";
+import { actionFor } from "./change-set.js";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** Whether an `after_unknown` value marks anything under it unknown. */
+function marks(v) {
+    if (v === true)
+        return true;
+    if (Array.isArray(v))
+        return v.some(marks);
+    if (isObject(v))
+        return Object.values(v).some(marks);
+    return false;
+}
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((x, i) => sameJson(x, b[i]));
+    if (isObject(a) && isObject(b)) {
+        const ka = Object.keys(a);
+        return ka.length === Object.keys(b).length && ka.every((k) => k in b && sameJson(a[k], b[k]));
+    }
+    return false;
+}
+/** Whether the value at `path` in an `after_unknown` tree is unknown: `true` at the path or on a prefix of it. */
+function unknownAt(tree, path) {
+    let at = tree;
+    for (const step of path) {
+        if (at === true)
+            return true;
+        if (Array.isArray(at) && typeof step === "number")
+            at = at[step];
+        else if (isObject(at) && typeof step === "string")
+            at = at[step];
+        else
+            return false;
+    }
+    return marks(at);
+}
+/**
+ * How a change replaces its resource. A `replace_paths` entry names an
+ * attribute whose change forces it. When every such attribute is unknown
+ * after apply, the plan cannot say the value will differ, so the replacement
+ * is `conditional`; one with a known forcing attribute is `true`. A delete
+ * and create pair with no `replace_paths` (a tainted object, `-replace`) is
+ * `true`. An update with none replaces nothing (`false`); a create or delete
+ * has no replacement to state.
+ */
+function replacementFor(change, action) {
+    const paths = (Array.isArray(change.replace_paths) ? change.replace_paths : []).filter(Array.isArray);
+    if (paths.length > 0)
+        return paths.every((p) => unknownAt(change.after_unknown, p)) ? "conditional" : "true";
+    if (action === "replace")
+        return "true";
+    if (action === "update")
+        return "false";
+    return undefined;
+}
+/**
+ * The shape of `planJson` (`terraform show -json`, from terraform, tofu or
+ * choudoufu) for `member`.
+ *
+ * One entry per `resource_changes` item that is not `no-op` or `read`.
+ * `logicalId` is the address, with `#<deposed>` for a deposed object. `type`
+ * is the resource type. `properties` are the top-level attributes that differ
+ * between `before` and `after` (on a create, those the plan sets or leaves
+ * unknown), and `unknown` the ones `after_unknown` marks, so `unknown` is
+ * within `properties`. A delete has no properties. Values never enter it, so
+ * a sensitive attribute is only a name.
+ */
+export function terraformPlanShape(planJson, member, options = {}) {
+    const plan = isObject(planJson) ? planJson : {};
+    const raw = Array.isArray(plan.resource_changes) ? plan.resource_changes : [];
+    const entries = [];
+    for (const r of raw) {
+        const rc = isObject(r) ? r : {};
+        const change = isObject(rc.change) ? rc.change : {};
+        const action = actionFor(change.actions);
+        if (action === "no-op" || action === "read")
+            continue;
+        const address = String(rc.address ?? "");
+        const before = isObject(change.before) ? change.before : {};
+        const after = isObject(change.after) ? change.after : {};
+        const afterUnknown = isObject(change.after_unknown) ? change.after_unknown : {};
+        const properties = [];
+        const unknown = [];
+        if (action !== "delete" && action !== "forget") {
+            for (const k of new Set([...Object.keys(before), ...Object.keys(after), ...Object.keys(afterUnknown)])) {
+                const isUnknown = marks(afterUnknown[k]);
+                const differs = action === "create"
+                    ? isUnknown || (after[k] !== undefined && after[k] !== null)
+                    : isUnknown || !sameJson(before[k] ?? null, after[k] ?? null);
+                if (!differs)
+                    continue;
+                properties.push(k);
+                if (isUnknown)
+                    unknown.push(k);
+            }
+        }
+        const replacement = replacementFor(change, action);
+        entries.push({
+            logicalId: typeof rc.deposed === "string" ? `${address}#${rc.deposed}` : address,
+            action,
+            ...(replacement ? { replacement } : {}),
+            ...(typeof rc.type === "string" ? { type: rc.type } : {}),
+            properties,
+            unknown,
+        });
+    }
+    return normalizePlanShape({
+        member,
+        entries,
+        unknownInputs: options.unknownInputs ?? [],
+        ...(options.knownInputs ? { knownInputs: options.knownInputs } : {}),
+    });
+}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAoElF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,aAkS7B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAsElF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,aAqT7B,CAAC"}

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { lastMemberReport, readPulumiMember, setLastMemberReport } from "./workspace-member.js";
+import { terraformCiSetup } from "./ci-setup.js";
 import { terraformBehaviourKinds } from "./behaviour/kinds.js";
 import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
 import { terraformSerializer } from "./serializer.js";
@@ -8,7 +8,7 @@ import { withCallersChain } from "./lint/post-synth/scope.js";
 import { terraformAuditCatalog } from "./lint/audit-catalog.js";
 import { completions } from "./lsp/completions.js";
 import { hover } from "./lsp/hover.js";
-import { terraformConfigSchema } from "./config.js";
+import { ownRoots, terraformConfigSchema } from "./config.js";
 import { renderTerraformRoots } from "./hcl/roots.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -17,6 +17,7 @@ import { descendModules } from "./hcl/descend.js";
 import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
 import { terraformCommands } from "./commands.js";
 import { terraformCapabilityPack } from "./capabilities/adapter.js";
+import { TERRAFORM_REFERENCE_CATALOG } from "./behaviour/reference-catalog.js";
 const loadSkills = createSkillsLoader(import.meta.url, [
     {
         file: "chant-terraform.md",
@@ -69,8 +70,14 @@ export const terraformPlugin = {
     behaviourKinds: terraformBehaviourKinds,
     name: "terraform",
     capabilityPack: terraformCapabilityPack,
+    // Keyed by provider type (#2360); see its module doc for which nodes it reads (#4535).
+    referenceCatalog: TERRAFORM_REFERENCE_CATALOG,
     serializer: terraformSerializer,
     configSchema: terraformConfigSchema,
+    // #4550: the engine install lines for the pull request pipeline's default image.
+    ciSetup(ctx) {
+        return terraformCiSetup(ctx);
+    },
     // ── Required lifecycle methods ────────────────────────────────
     async generate(options) {
         const { generate } = await import("./codegen/generate.js");
@@ -120,6 +127,17 @@ export const terraformPlugin = {
         const { describeResources } = await import("./describe-resources.js");
         return describeResources(options);
     },
+    /**
+     * Each root's drift, as drift-record stream lines (behold#995): a stock
+     * root through its state or a plan, a live root through `live-plan` (and a
+     * plan), one resource through `live-plan -resource`. `chant workspace
+     * drift` reaches it through `chant lifecycle drift` in a member's reader
+     * project. See `./drift-read.ts`.
+     */
+    async readDrift(options) {
+        const { readTerraformDrift } = await import("./drift-read.js");
+        return readTerraformDrift(options);
+    },
     /**
      * The prediction, for whichever estate `options.from` names (#2495). The
      * producer is `predictTerraformBehaviour` and this is its second caller, not
@@ -156,15 +174,9 @@ export const terraformPlugin = {
      * project root, which is what relative `dir` paths resolve against.
      */
     async buildRoots(ctx) {
-        setLastMemberReport(undefined);
         const namespace = ctx.config.terraform;
-        // A pulumi workspace member (#3179): its checked-in stack export, never the program.
-        if (namespace?.pulumiMember) {
-            const read = readPulumiMember({ member: namespace.pulumiMember });
-            setLastMemberReport(read.report);
-            return { entities: read.entities, warnings: read.warnings };
-        }
-        const roots = namespace?.roots ?? {};
+        // A `signalOnly` root (#4484) feeds change detection only, so it builds no entities here.
+        const roots = ownRoots(namespace?.roots);
         if (Object.keys(roots).length === 0)
             return { entities: new Map(), warnings: [] };
         return renderTerraformRoots({
@@ -175,10 +187,6 @@ export const terraformPlugin = {
             moduleRoot: namespace?.moduleRoot,
         });
     },
-    graphMeta() {
-        const report = lastMemberReport();
-        return report ? { pulumiMember: report } : undefined;
-    },
     /** `chant terraform pin-rollout` (#3189). */
     commands() {
         return terraformCommands;
@@ -186,14 +194,16 @@ export const terraformPlugin = {
     /**
      * 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`.
+     * See `./changed-roots.ts`. Every root counts, a `signalOnly` one too
+     * (#4484): that is what it is declared for.
      */
     async changedUnits(ctx) {
-        const roots = ctx.config.terraform?.roots ?? {};
+        const tf = ctx.config.terraform;
+        const roots = tf?.roots ?? {};
         if (Object.keys(roots).length === 0)
             return [];
         const { changedRoots } = await import("./changed-roots.js");
-        return changedRoots(ctx.projectRoot, roots, ctx.changedFiles);
+        return changedRoots(ctx.projectRoot, roots, ctx.changedFiles, tf?.binary);
     },
     lintRules() {
         return rules;
@@ -263,13 +273,22 @@ export const terraformPlugin = {
             // 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 });
+            // An audit has no `terraform.binary` to follow (chant#4457). A root
+            // that carries a `.tofu` file is written for OpenTofu, so it is read
+            // as a tofu root; any other is read as terraform, the config default.
+            const binary = /^# file: .*\.tofu(\.json)?\s*$/m.test(content) ? "tofu" : undefined;
+            const modeOptions = {
+                ...(binary !== undefined ? { binary } : {}),
+                ...(lockFile !== undefined ? { lockFile } : {}),
+            };
+            const entities = await parseTerraformRootContent(content, root, undefined, Object.keys(modeOptions).length > 0 ? modeOptions : undefined);
             if (input?.dir === undefined)
                 return entities;
             const { entities: children } = await descendModules(entities, {
                 dir: input.dir,
                 root,
                 projectRoot: input.baseDir ?? input.dir,
+                ...(binary !== undefined ? { modeOptions: { binary } } : {}),
             });
             for (const [key, entity] of children)
                 entities.set(key, entity);

package/dist/registry/address.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Where a module sits in a Terraform module registry, and how a registry
+ * source (`<host>/<namespace>/<name>/<system>`) is split into those parts.
+ * Lifted from terragucci's `publish/registry.ts` (18f6431595) for chant#4565.
+ * No Node imports, so an edge function can carry it.
+ */
+export declare const DISCOVERY = ".well-known/terraform.json";
+export declare const MODULES_V1 = "/v1/modules/";
+export declare const DEFAULT_SYSTEM = "generic";
+/** A registry namespace or module name: letters, digits, `-` and `_`, starting and ending on a letter or digit. */
+export declare const REGISTRY_NAME: RegExp;
+/** A registry module's system (its target provider): lower-case letters and digits. */
+export declare const REGISTRY_SYSTEM: RegExp;
+/** Where a module is in the registry. */
+export interface RegistryAddress {
+    namespace: string;
+    name: string;
+    system: string;
+    /** `<host>/<namespace>/<name>/<system>`, the source a root writes. */
+    source: string;
+    /** The module's directory under the registry root: `v1/modules/<namespace>/<name>/<system>`. */
+    path: string;
+}
+/** What placing a module needs from a registry's settings. */
+export interface RegistryPlacement {
+    /** The registry's base URL; its host is what sources name. */
+    url: string;
+    namespace: string;
+    /** A namespace per path prefix, the longest prefix winning. */
+    namespaces?: Record<string, string>;
+    system?: string;
+}
+/** A module name the protocol cannot carry. */
+export declare class RegistryNameError extends Error {
+    constructor(message: string);
+}
+/** The host a registry's sources name: its URL without the scheme, lower-cased. */
+export declare const registryHost: (reg: Pick<RegistryPlacement, "url">) => string;
+/** The namespace a module's path goes under: the longest `namespaces` prefix it starts with, else `namespace`. */
+export declare function namespaceFor(reg: Pick<RegistryPlacement, "namespace" | "namespaces">, rel: string): string;
+/** A module's place in the registry: its namespace, its name (the last segment of its path) and its system. */
+export declare function registryAddress(reg: RegistryPlacement, rel: string): RegistryAddress;
+/** A registry source split into its parts. */
+export interface RegistrySource {
+    host: string;
+    namespace: string;
+    name: string;
+    system: string;
+}
+/**
+ * A registry source split into its host and module, or undefined when the
+ * source is not one: `host/ns/name/system`, with an optional `//subdir` and
+ * query. The host must look like one (a dot, a port, or `localhost`), so a
+ * three-part public registry source with no host is not taken for one.
+ * `hosts` names bare hosts a CLI `host` block declares (a Nexus repository's
+ * name, chant#4605), which are taken as hosts too.
+ */
+export declare function parseRegistrySource(source: string, hosts?: readonly string[]): RegistrySource | undefined;
+/** A key under a registry's prefix in its bucket or directory. */
+export declare const keyFor: (prefix: string | undefined, path: string) => string;
+/** The tarball's name beside its version. */
+export declare const tarballName: (addr: Pick<RegistryAddress, "name">, version: string) => string;
+//# sourceMappingURL=address.d.ts.map

package/dist/registry/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/registry/address.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,SAAS,+BAA+B,CAAC;AACtD,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,mHAAmH;AACnH,eAAO,MAAM,aAAa,QAAqD,CAAC;AAChF,uFAAuF;AACvF,eAAO,MAAM,eAAe,QAAqB,CAAC;AAElD,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,mFAAmF;AACnF,eAAO,MAAM,YAAY,QAAS,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,KAAG,MAA6C,CAAC;AAEjH,kHAAkH;AAClH,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ1G;AAED,+GAA+G;AAC/G,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAMpF;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,SAAS,MAAM,EAAO,GAAG,cAAc,GAAG,SAAS,CAM7G;AAED,kEAAkE;AAClE,eAAO,MAAM,MAAM,WAAY,MAAM,GAAG,SAAS,QAAQ,MAAM,KAAG,MAGjE,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,WAAW,SAAU,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,WAAW,MAAM,KAAG,MAA0C,CAAC"}

package/dist/registry/address.js

@@ -0,0 +1,65 @@
+/**
+ * Where a module sits in a Terraform module registry, and how a registry
+ * source (`<host>/<namespace>/<name>/<system>`) is split into those parts.
+ * Lifted from terragucci's `publish/registry.ts` (18f6431595) for chant#4565.
+ * No Node imports, so an edge function can carry it.
+ */
+export const DISCOVERY = ".well-known/terraform.json";
+export const MODULES_V1 = "/v1/modules/";
+export const DEFAULT_SYSTEM = "generic";
+/** A registry namespace or module name: letters, digits, `-` and `_`, starting and ending on a letter or digit. */
+export const REGISTRY_NAME = /^[0-9A-Za-z](?:[0-9A-Za-z_-]{0,62}[0-9A-Za-z])?$/;
+/** A registry module's system (its target provider): lower-case letters and digits. */
+export const REGISTRY_SYSTEM = /^[0-9a-z]{1,64}$/;
+/** A module name the protocol cannot carry. */
+export class RegistryNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegistryNameError";
+    }
+}
+/** The host a registry's sources name: its URL without the scheme, lower-cased. */
+export const registryHost = (reg) => new URL(reg.url).host.toLowerCase();
+/** The namespace a module's path goes under: the longest `namespaces` prefix it starts with, else `namespace`. */
+export function namespaceFor(reg, rel) {
+    let best;
+    for (const [prefix, ns] of Object.entries(reg.namespaces ?? {})) {
+        const p = prefix.replace(/^\.\//, "");
+        const dir = p.endsWith("/") ? p : `${p}/`;
+        if ((rel.startsWith(dir) || rel === p.replace(/\/+$/, "")) && (!best || p.length > best.prefix.length))
+            best = { prefix: p, ns };
+    }
+    return best?.ns ?? reg.namespace;
+}
+/** A module's place in the registry: its namespace, its name (the last segment of its path) and its system. */
+export function registryAddress(reg, rel) {
+    const namespace = namespaceFor(reg, rel);
+    const name = rel.replace(/\/+$/, "").split("/").pop() ?? "";
+    const system = reg.system ?? DEFAULT_SYSTEM;
+    if (!REGISTRY_NAME.test(name))
+        throw new RegistryNameError(`${rel}: a registry module's name is letters, digits, - and _, and ${JSON.stringify(name)} is not; rename the directory`);
+    return { namespace, name, system, source: `${registryHost(reg)}/${namespace}/${name}/${system}`, path: `v1/modules/${namespace}/${name}/${system}` };
+}
+/**
+ * A registry source split into its host and module, or undefined when the
+ * source is not one: `host/ns/name/system`, with an optional `//subdir` and
+ * query. The host must look like one (a dot, a port, or `localhost`), so a
+ * three-part public registry source with no host is not taken for one.
+ * `hosts` names bare hosts a CLI `host` block declares (a Nexus repository's
+ * name, chant#4605), which are taken as hosts too.
+ */
+export function parseRegistrySource(source, hosts = []) {
+    const base = source.split("?")[0].split("//")[0];
+    const m = /^([a-z0-9.-]+(?::\d+)?)\/([^/]+)\/([^/]+)\/([^/]+)$/i.exec(base);
+    const known = (h) => hosts.some((k) => k.toLowerCase() === h.toLowerCase());
+    if (!m || (!m[1].includes(".") && !m[1].includes(":") && m[1] !== "localhost" && !known(m[1])))
+        return undefined;
+    return { host: m[1].toLowerCase(), namespace: m[2], name: m[3], system: m[4] };
+}
+/** A key under a registry's prefix in its bucket or directory. */
+export const keyFor = (prefix, path) => {
+    const p = (prefix ?? "").replace(/^\/+|\/+$/g, "");
+    return p ? `${p}/${path}` : path;
+};
+/** The tarball's name beside its version. */
+export const tarballName = (addr, version) => `${addr.name}-${version}.tar.gz`;