@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/registry/targets/zip.js

@@ -0,0 +1,278 @@
+/**
+ * The zip of an attested module archive (chant#4605, terragucci#1299 ruling
+ * A). Artifactory takes a module only as a zip and Nexus recommends one, so
+ * their targets upload the same files the bucket registry's `.tar.gz`
+ * carries, at the same paths with the same modes, repacked as a zip. Nothing
+ * is added to or dropped from the module.
+ *
+ * The repack is deterministic: entries keep the tarball's order and mtimes,
+ * so one archive always gives the same zip bytes. The zip's archive comment
+ * carries the attested content digest and the revision
+ * (`chant-module content=sha256:<hex> revision=<sha>`), which is how a
+ * target's `held` tells, from the zip a host gives back, which attested
+ * archive it was made from. A zip with no such comment (one uploaded by
+ * hand) is judged by its own digest, so it never passes for the release's.
+ *
+ * No zip64: an archive past 4 GiB or 65535 entries is refused, far above
+ * either host's limit (Nexus takes 100 MB per module).
+ */
+import { deflateRawSync, gunzipSync, inflateRawSync } from "node:zlib";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+const field = (b, at, len) => {
+    const raw = b.subarray(at, at + len);
+    const end = raw.indexOf(0);
+    return raw.subarray(0, end < 0 ? raw.length : end).toString("utf-8");
+};
+const octal = (b, at, len) => parseInt(field(b, at, len).trim() || "0", 8);
+function paxRecords(data) {
+    const out = {};
+    let at = 0;
+    while (at < data.length) {
+        const space = data.indexOf(0x20, at);
+        if (space < 0)
+            break;
+        const len = parseInt(data.subarray(at, space).toString("utf-8"), 10);
+        if (!Number.isFinite(len) || len <= 0)
+            break;
+        const record = data.subarray(space + 1, at + len - 1).toString("utf-8");
+        const eq = record.indexOf("=");
+        if (eq > 0)
+            out[record.slice(0, eq)] = record.slice(eq + 1);
+        at += len;
+    }
+    return out;
+}
+const invalid = (message) => new PublishTargetError("publish-archive-invalid", message, "Publish the .tar.gz the bucket registry serves, with the module's files at its root.");
+/**
+ * The entries of a module's gzip tarball (ustar, pax and GNU long names), with
+ * `./` cut from each path. A link or a device in the archive is refused: a
+ * zip of the module could not carry it as the tarball does.
+ */
+export function moduleArchiveEntries(archive) {
+    let tar;
+    try {
+        tar = gunzipSync(archive);
+    }
+    catch {
+        throw invalid("the module archive is not a gzip tarball");
+    }
+    const out = [];
+    let at = 0;
+    let pax = {};
+    let longName;
+    while (at + 512 <= tar.length) {
+        const header = tar.subarray(at, at + 512);
+        if (header.every((b) => b === 0))
+            break;
+        const size = octal(header, 124, 12);
+        const flag = String.fromCharCode(header[156] || 0x30);
+        const data = tar.subarray(at + 512, at + 512 + size);
+        at += 512 + Math.ceil(size / 512) * 512;
+        if (flag === "x") {
+            pax = paxRecords(data);
+            continue;
+        }
+        if (flag === "L") {
+            longName = field(data, 0, data.length);
+            continue;
+        }
+        if (flag === "g")
+            continue;
+        const prefix = field(header, 345, 155);
+        const raw = pax.path ?? longName ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100));
+        const mtime = pax.mtime ? Math.floor(Number(pax.mtime)) : octal(header, 136, 12);
+        pax = {};
+        longName = undefined;
+        const path = raw.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+        if (!path || path === ".")
+            continue;
+        if (path.startsWith("/") || path.split("/").includes(".."))
+            throw invalid(`the module archive holds ${raw}, outside its root`);
+        const type = flag === "0" || flag === "\0" || flag === "7" ? "file" : flag === "5" ? "dir" : undefined;
+        if (!type)
+            throw invalid(`the module archive holds ${path}, which is not a regular file or a directory; a zip of the module cannot carry it`);
+        out.push({ path, type, mode: octal(header, 100, 8) & 0o7777, mtime, data: type === "file" ? Buffer.from(data) : Buffer.alloc(0) });
+    }
+    return out;
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+/** The CRC-32 a zip entry carries. */
+export function crc32(data) {
+    let c = 0xffffffff;
+    for (let i = 0; i < data.length; i++)
+        c = CRC_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** MS-DOS date and time, as a zip entry keeps them, in UTC and clamped to 1980. */
+function dosTime(seconds) {
+    const d = new Date(Math.max(seconds * 1000, Date.UTC(1980, 0, 1)));
+    return {
+        time: (d.getUTCHours() << 11) | (d.getUTCMinutes() << 5) | Math.floor(d.getUTCSeconds() / 2),
+        date: ((d.getUTCFullYear() - 1980) << 9) | ((d.getUTCMonth() + 1) << 5) | d.getUTCDate(),
+    };
+}
+/** The archive comment that names the attested archive a zip was made from. */
+export const ZIP_COMMENT_PREFIX = "chant-module";
+export const moduleZipComment = (content, revision) => `${ZIP_COMMENT_PREFIX} content=${content}${revision ? ` revision=${revision}` : ""}`;
+/** The content and revision a zip's archive comment names, when it is one {@link moduleZipComment} wrote. */
+export function readModuleZipComment(comment) {
+    if (!comment.startsWith(`${ZIP_COMMENT_PREFIX} `))
+        return undefined;
+    const content = /(?:^| )content=(sha256:[0-9a-f]{64})(?: |$)/.exec(comment)?.[1];
+    if (!content)
+        return undefined;
+    const revision = /(?:^| )revision=([^ ]+)(?: |$)/.exec(comment)?.[1];
+    return { content, ...(revision ? { revision } : {}) };
+}
+/** A zip of the given entries, with `comment` as its archive comment. Files are deflated. */
+export function zipOf(entries, comment = "") {
+    if (entries.length > 0xffff)
+        throw invalid(`the module archive holds ${entries.length} entries; a zip without zip64 holds 65535`);
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const e of entries) {
+        const name = Buffer.from(e.type === "dir" ? `${e.path}/` : e.path, "utf-8");
+        const data = e.type === "file" ? e.data : Buffer.alloc(0);
+        const packed = e.type === "file" ? deflateRawSync(data, { level: 9 }) : Buffer.alloc(0);
+        const method = e.type === "file" ? 8 : 0;
+        const crc = crc32(data);
+        const { time, date } = dosTime(e.mtime);
+        if (packed.length > 0xfffffffe || data.length > 0xfffffffe || offset > 0xfffffffe)
+            throw invalid("the module archive is past 4 GiB; a zip without zip64 holds less");
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(method, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(packed.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        locals.push(local, name, packed);
+        const unixMode = (e.type === "dir" ? 0o040000 : 0o100000) | (e.mode & 0o7777 || (e.type === "dir" ? 0o755 : 0o644));
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE((3 << 8) | 20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(method, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(date, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(packed.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt16LE(0, 30);
+        central.writeUInt16LE(0, 32);
+        central.writeUInt16LE(0, 34);
+        central.writeUInt16LE(0, 36);
+        central.writeUInt32LE(((unixMode << 16) | (e.type === "dir" ? 0x10 : 0)) >>> 0, 38);
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, name);
+        offset += local.length + name.length + packed.length;
+    }
+    const cd = Buffer.concat(centrals);
+    const note = Buffer.from(comment, "utf-8");
+    if (note.length > 0xffff)
+        throw invalid("the zip comment is longer than a zip carries");
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(0, 4);
+    end.writeUInt16LE(0, 6);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(cd.length, 12);
+    end.writeUInt32LE(offset, 16);
+    end.writeUInt16LE(note.length, 20);
+    return Buffer.concat([...locals, cd, end, note]);
+}
+/**
+ * The zip a hosted target uploads for an attested archive: its entries,
+ * repacked, with the content digest and revision in the archive comment.
+ */
+export function moduleZip(archive, content, revision) {
+    return zipOf(moduleArchiveEntries(archive), moduleZipComment(content, revision));
+}
+/** Reads a zip's central directory and entries. Throws on bytes that are not a zip. */
+export function readZip(bytes) {
+    const b = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let end = -1;
+    for (let i = b.length - 22; i >= Math.max(0, b.length - 22 - 0xffff); i--) {
+        if (b.readUInt32LE(i) === 0x06054b50) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        throw new Error("not a zip archive: no end of central directory");
+    const count = b.readUInt16LE(end + 10);
+    const cdOffset = b.readUInt32LE(end + 16);
+    const comment = b.subarray(end + 22, end + 22 + b.readUInt16LE(end + 20)).toString("utf-8");
+    const entries = [];
+    let at = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (b.readUInt32LE(at) !== 0x02014b50)
+            throw new Error("not a zip archive: a bad central directory entry");
+        const method = b.readUInt16LE(at + 10);
+        const csize = b.readUInt32LE(at + 20);
+        const nameLen = b.readUInt16LE(at + 28);
+        const extraLen = b.readUInt16LE(at + 30);
+        const commentLen = b.readUInt16LE(at + 32);
+        const external = b.readUInt32LE(at + 38);
+        const local = b.readUInt32LE(at + 42);
+        const name = b.subarray(at + 46, at + 46 + nameLen).toString("utf-8");
+        at += 46 + nameLen + extraLen + commentLen;
+        if (b.readUInt32LE(local) !== 0x04034b50)
+            throw new Error(`not a zip archive: no local header for ${name}`);
+        const start = local + 30 + b.readUInt16LE(local + 26) + b.readUInt16LE(local + 28);
+        const packed = b.subarray(start, start + csize);
+        const data = method === 0 ? Buffer.from(packed) : method === 8 ? inflateRawSync(packed) : undefined;
+        if (!data)
+            throw new Error(`${name}: zip method ${method} is not read here`);
+        const dir = name.endsWith("/");
+        entries.push({ path: dir ? name.slice(0, -1) : name, dir, mode: (external >>> 16) & 0o7777, data });
+    }
+    return { comment, entries };
+}
+const isGzip = (b) => b.length >= 2 && b[0] === 0x1f && b[1] === 0x8b;
+const isZip = (b) => b.length >= 4 && b[0] === 0x50 && b[1] === 0x4b;
+/**
+ * The content a module archive a host gave back carries, as `held` reports
+ * it: the attested digest a chant zip's comment names; for a gzip tarball,
+ * the digest of its uncompressed bytes, as the bucket registry keeps it; for
+ * any other bytes, their own digest.
+ */
+export function heldContentOf(bytes, digest) {
+    if (isZip(bytes)) {
+        try {
+            const named = readModuleZipComment(readZip(bytes).comment);
+            if (named)
+                return named;
+        }
+        catch {
+            // Not a zip after all: judged by its own digest below.
+        }
+    }
+    else if (isGzip(bytes)) {
+        try {
+            return { content: digest(gunzipSync(bytes)) };
+        }
+        catch {
+            // A broken gzip: judged by its own digest below.
+        }
+    }
+    return { content: digest(bytes) };
+}

package/dist/registry/writer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The module registry protocol, written as files a bucket, a directory or a
+ * Pages site holds (https://opentofu.org/docs/internals/module-registry-protocol/):
+ *
+ *   .well-known/terraform.json                  {"modules.v1": "/v1/modules/"}
+ *   v1/modules/<ns>/<name>/<system>/versions     every version, oldest first
+ *   v1/modules/<ns>/<name>/<system>/<v>/download {"location": ...}
+ *   v1/modules/<ns>/<name>/<system>/<v>/<name>-<v>.tar.gz   a tarball download
+ *   v1/modules/<ns>/<name>/<system>/<v>/release.json        the commit and content digest
+ *
+ * The download answer the two CLIs need is a 200 with the JSON body and an
+ * `X-Terraform-Get` header naming the same location (terragucci#1287).
+ * Terraform reads only the header (hashicorp/terraform
+ * internal/registry/client.go:237-250 at v1.14.9 and v1.15.8). OpenTofu reads
+ * the body's `location` first and the header when it is empty
+ * (opentofu/opentofu internal/registry/client.go:205-237 at v1.12.5 and
+ * v1.13.1). A stored file carries no header, so the stored `download` file is
+ * the body, and whatever serves it (`downloadAnswer`, the loopback handler in
+ * ./serve, an edge function) adds the header from that body.
+ *
+ * The writer takes the store it writes to, so the bucket clients stay with
+ * whoever owns them (chant#4554 moves terragucci's into core).
+ */
+import { type StoreCondition } from "@intentius/chant/object-store/errors";
+import { type RegistryAddress } from "./address.js";
+import { type Semver } from "./semver.js";
+/** The header Terraform takes a module's location from. */
+export declare const DOWNLOAD_HEADER = "X-Terraform-Get";
+/** The files a registry is written to: a bucket client, a directory, or a test's map. */
+export interface RegistryWriteStore {
+    /** Writes one object. With `when`, the write must fail with a conflict when the condition no longer holds. */
+    put(key: string, body: string | Buffer, contentType?: string, when?: StoreCondition): Promise<unknown>;
+    /** One object's body and version tag, or `{}` when there is none. */
+    read(key: string): Promise<{
+        body?: string;
+        etag?: string;
+    }>;
+}
+/** The service discovery document. */
+export declare const discoveryDoc: () => string;
+/** The protocol's versions answer, oldest first, duplicates and non-versions dropped. */
+export declare function versionsDoc(versions: string[]): string;
+/** The versions a versions answer lists, or none when it is missing or not the protocol's JSON. */
+export declare function readVersions(text: string | undefined): string[];
+/** A version's download answer body: the JSON OpenTofu reads. */
+export declare function downloadDoc(location: string): string;
+/** The location a download body names, or undefined when it names none. */
+export declare function downloadLocation(body: string | undefined): string | undefined;
+/** A download answer as a server sends it. */
+export interface DownloadAnswer {
+    status: 200;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * The download answer both CLIs install from: status 200, the JSON body with
+ * `location`, and `X-Terraform-Get` naming the same location.
+ */
+export declare function downloadAnswer(location: string): DownloadAnswer;
+/** The headers a stored download body is served with, or undefined when the body names no location. */
+export declare function downloadHeaders(body: string | undefined): Record<string, string> | undefined;
+/** True for a `.../v1/modules/<ns>/<name>/<system>/<version>/download` path, with or without a leading prefix. */
+export declare const isDownloadPath: (path: string) => boolean;
+/** What the registry keeps beside a version, so the next publish knows what it holds. */
+export interface ReleaseMeta {
+    module: string;
+    version: string;
+    revision: string;
+    content: string;
+    location: string;
+}
+/** The registry's files for one version, written in this order: the version is listed last, once all it points at is there. */
+export interface VersionFiles {
+    tarball?: {
+        key: string;
+        body: Buffer;
+    };
+    download: {
+        key: string;
+        body: string;
+    };
+    meta: {
+        key: string;
+        body: string;
+    };
+}
+export interface WriteVersionOptions {
+    /** The registry's prefix in its store. */
+    prefix?: string;
+    /**
+     * Whether an error from `put` is a lost conditional write, to be retried.
+     * By default chant's `StoreConflict`, or any error named `StoreConflict`
+     * (a store from another package with a class of its own).
+     */
+    isConflict?: (e: unknown) => boolean;
+    /** Conditional retries on the versions file before the conflict is thrown. Default 3. */
+    retries?: number;
+}
+/** Writes one version: discovery when it differs, the tarball, the download answer, release.json, then the versions list. */
+export declare function writeVersion(store: RegistryWriteStore, addr: RegistryAddress, version: Semver, files: VersionFiles, options?: WriteVersionOptions): Promise<void>;
+//# sourceMappingURL=writer.d.ts.map

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

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

package/dist/registry/writer.js

@@ -0,0 +1,109 @@
+/**
+ * The module registry protocol, written as files a bucket, a directory or a
+ * Pages site holds (https://opentofu.org/docs/internals/module-registry-protocol/):
+ *
+ *   .well-known/terraform.json                  {"modules.v1": "/v1/modules/"}
+ *   v1/modules/<ns>/<name>/<system>/versions     every version, oldest first
+ *   v1/modules/<ns>/<name>/<system>/<v>/download {"location": ...}
+ *   v1/modules/<ns>/<name>/<system>/<v>/<name>-<v>.tar.gz   a tarball download
+ *   v1/modules/<ns>/<name>/<system>/<v>/release.json        the commit and content digest
+ *
+ * The download answer the two CLIs need is a 200 with the JSON body and an
+ * `X-Terraform-Get` header naming the same location (terragucci#1287).
+ * Terraform reads only the header (hashicorp/terraform
+ * internal/registry/client.go:237-250 at v1.14.9 and v1.15.8). OpenTofu reads
+ * the body's `location` first and the header when it is empty
+ * (opentofu/opentofu internal/registry/client.go:205-237 at v1.12.5 and
+ * v1.13.1). A stored file carries no header, so the stored `download` file is
+ * the body, and whatever serves it (`downloadAnswer`, the loopback handler in
+ * ./serve, an edge function) adds the header from that body.
+ *
+ * The writer takes the store it writes to, so the bucket clients stay with
+ * whoever owns them (chant#4554 moves terragucci's into core).
+ */
+// The errors module alone, never the object-store index: its clients import Node built-ins, and the
+// edge function (./edge) reaches this file for the download answer (chant#4589).
+import { isStoreConflict } from "@intentius/chant/object-store/errors";
+import { DISCOVERY, MODULES_V1, keyFor } from "./address.js";
+import { compareSemver, formatSemver, parseSemver } from "./semver.js";
+/** The header Terraform takes a module's location from. */
+export const DOWNLOAD_HEADER = "X-Terraform-Get";
+/** The service discovery document. */
+export const discoveryDoc = () => `${JSON.stringify({ "modules.v1": MODULES_V1 })}\n`;
+/** The protocol's versions answer, oldest first, duplicates and non-versions dropped. */
+export function versionsDoc(versions) {
+    // Dedupe after formatting, so "v1.0.0" and "1.0.0" are one version.
+    const parsed = versions.map((v) => parseSemver(v)).filter((v) => !!v);
+    const sorted = [...new Set(parsed.sort(compareSemver).map(formatSemver))];
+    return `${JSON.stringify({ modules: [{ versions: sorted.map((version) => ({ version })) }] }, null, 2)}\n`;
+}
+/** The versions a versions answer lists, or none when it is missing or not the protocol's JSON. */
+export function readVersions(text) {
+    if (!text)
+        return [];
+    try {
+        const doc = JSON.parse(text);
+        return (doc.modules?.[0]?.versions ?? []).map((v) => v.version).filter((v) => typeof v === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/** A version's download answer body: the JSON OpenTofu reads. */
+export function downloadDoc(location) {
+    return `${JSON.stringify({ location })}\n`;
+}
+/** The location a download body names, or undefined when it names none. */
+export function downloadLocation(body) {
+    if (!body)
+        return undefined;
+    try {
+        const location = JSON.parse(body).location;
+        return typeof location === "string" && location ? location : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The download answer both CLIs install from: status 200, the JSON body with
+ * `location`, and `X-Terraform-Get` naming the same location.
+ */
+export function downloadAnswer(location) {
+    return { status: 200, headers: { "content-type": "application/json", [DOWNLOAD_HEADER]: location }, body: downloadDoc(location) };
+}
+/** The headers a stored download body is served with, or undefined when the body names no location. */
+export function downloadHeaders(body) {
+    const location = downloadLocation(body);
+    return location ? downloadAnswer(location).headers : undefined;
+}
+/** True for a `.../v1/modules/<ns>/<name>/<system>/<version>/download` path, with or without a leading prefix. */
+export const isDownloadPath = (path) => /(^|\/)v1\/modules\/[^/]+\/[^/]+\/[^/]+\/[^/]+\/download$/.test(path.split("?")[0]);
+/** Writes one version: discovery when it differs, the tarball, the download answer, release.json, then the versions list. */
+export async function writeVersion(store, addr, version, files, options = {}) {
+    const discovery = discoveryDoc();
+    const discoKey = keyFor(options.prefix, DISCOVERY);
+    const disco = await store.read(discoKey);
+    if (disco.body !== discovery)
+        await store.put(discoKey, discovery, "application/json");
+    if (files.tarball)
+        await store.put(files.tarball.key, files.tarball.body, "application/gzip");
+    await store.put(files.download.key, files.download.body, "application/json");
+    await store.put(files.meta.key, files.meta.body, "application/json");
+    const key = keyFor(options.prefix, `${addr.path}/versions`);
+    const isConflict = options.isConflict ?? isStoreConflict;
+    const retries = options.retries ?? 3;
+    // Read, add, write only over the copy read: two publishes at once cannot drop each other's version.
+    for (let attempt = 0;; attempt++) {
+        const held = await store.read(key);
+        const when = held.body === undefined ? { ifNoneMatch: "*" } : held.etag ? { ifMatch: held.etag } : undefined;
+        try {
+            await store.put(key, versionsDoc([...readVersions(held.body), formatSemver(version)]), "application/json", when);
+            return;
+        }
+        catch (e) {
+            if (!isConflict(e) || attempt >= retries)
+                throw e;
+        }
+    }
+}

package/dist/rules/record-store.ts

@@ -0,0 +1,122 @@
+/**
+ * The record store a live root resolves to, read from its HCL the way
+ * choudoufu resolves it (INTENTIUS/choudoufu#2293, `internal/configs/live_derive.go`
+ * at choudoufu 74ffde956bfd97f44b8ad444424584e23321adc2). Shared by TF024,
+ * which names where records go, and TF046, which guards a CI root that ends
+ * up on the local store, so the two never disagree.
+ *
+ * The order is choudoufu's:
+ *
+ * 1. A `record_store "<kind>"` block in the `live` block or the
+ *    `estate.chdf.hcl` sidecar always wins (`source: "record_store"`).
+ * 2. Otherwise the backend block choudoufu ignores under live gives the store,
+ *    s3 to s3, gcs to gcs, azurerm to azurerm (`source: "backend"`). s3 and gcs
+ *    need a literal `bucket`; azurerm needs literal `storage_account_name`,
+ *    `container_name` and `resource_group_name`. A value passed only with
+ *    `-backend-config` is not in the configuration, so choudoufu does not see
+ *    it either.
+ * 3. Otherwise the store is local (`source: "implied"`), with `note` saying
+ *    why a backend that was there was not used.
+ *
+ * This mirrors `record_store.source` and `record_store.note` in
+ * `choudoufu live-check -json`. A literal here is a string hcl2json hands back
+ * with no `${...}` in it, the same "not determined" reading the Terragrunt
+ * rules use (`./terragrunt.ts`).
+ */
+
+import type { BlockBody } from "../../hcl/parse";
+import { backendTypes } from "./tf001";
+import { isExpression } from "./terragrunt";
+
+export type RecordStoreSource = "record_store" | "backend" | "implied";
+
+export interface ResolvedRecordStore {
+  /** `local`, `s3`, `gcs`, `azurerm` or `kubernetes`, or whatever label a `record_store` block carries. */
+  kind: string;
+  source: RecordStoreSource;
+  /** The backend type the store came from, or was not derived from, when there is a backend block. */
+  backend?: string;
+  /** Why a backend block that was present did not give a store. Set only with `source: "implied"`. */
+  note?: string;
+}
+
+/** Backend types choudoufu derives a record store from (INTENTIUS/choudoufu#2293). */
+export const DERIVABLE_BACKENDS: ReadonlySet<string> = new Set(["s3", "gcs", "azurerm"]);
+
+const asRecord = (v: unknown): BlockBody =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as BlockBody) : {};
+
+const firstBody = (v: unknown): BlockBody => asRecord(Array.isArray(v) ? v[0] : v);
+
+/**
+ * The label of a `record_store "<kind>"` block in a live declaration body, or
+ * undefined when it declares none. hcl2json nests the label one level down,
+ * as it does for `backend` (see `backendTypes` in `./tf001.ts`).
+ */
+export function recordStoreKind(liveBody: BlockBody): string | undefined {
+  const raw = liveBody["record_store"];
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const labels = Object.keys(raw as BlockBody);
+  return labels[0];
+}
+
+/** A top-level backend argument as a literal string, or undefined when it is absent, empty or an expression. */
+function literal(body: BlockBody, name: string): string | undefined {
+  const v = body[name];
+  if (typeof v !== "string" || v === "" || isExpression(v)) return undefined;
+  return v;
+}
+
+/**
+ * Why a backend block gives no record store, or undefined when it gives one.
+ * The wording follows choudoufu's `Live.RecordStoreNote`; an empty string
+ * means no store and nothing to say (a `local` backend).
+ */
+function derivationNote(type: string, body: BlockBody): string | undefined {
+  const where = `backend "${type}"`;
+  switch (type) {
+    case "s3":
+    case "gcs":
+      return literal(body, "bucket") === undefined
+        ? `${where} sets no literal bucket; values passed with -backend-config are not read`
+        : undefined;
+    case "azurerm":
+      for (const name of ["storage_account_name", "container_name", "resource_group_name"]) {
+        if (literal(body, name) === undefined) return `${where} sets no literal ${name}, which the azurerm record store needs`;
+      }
+      return undefined;
+    case "local":
+      // choudoufu leaves no note here: a local backend and the local store agree.
+      return "";
+    default:
+      return `${where} has no record store counterpart`;
+  }
+}
+
+/**
+ * Resolve one live root's record store.
+ *
+ * `terraformBodies` are the bodies of every `terraform` block in the root (a
+ * backend can sit in a separate `backend.tf`). `liveBodies` are the root's
+ * live declarations: its `live` block and its sidecar, if any. choudoufu
+ * refuses a root that has both, so the first `record_store` found is the one.
+ */
+export function resolveRecordStore(
+  terraformBodies: readonly BlockBody[],
+  liveBodies: readonly BlockBody[],
+): ResolvedRecordStore {
+  for (const live of liveBodies) {
+    const kind = recordStoreKind(live);
+    if (kind !== undefined) return { kind, source: "record_store" };
+  }
+  for (const tf of terraformBodies) {
+    const type = backendTypes(tf)[0];
+    if (type === undefined) continue;
+    const body = firstBody(asRecord(tf["backend"])[type]);
+    const note = derivationNote(type, body);
+    if (note === undefined) return { kind: type, source: "backend", backend: type };
+    return { kind: "local", source: "implied", backend: type, ...(note ? { note } : {}) };
+  }
+  return { kind: "local", source: "implied" };
+}

package/dist/rules/tf001.ts

@@ -30,8 +30,8 @@
  * module's `terraform` block is skipped here rather than read as if it were
  * the root's.
  *
- * Does not fire on a live root (#2103): a `backend` block is exactly what
- * choudoufu refuses there (TF024's territory), and the fallback to local
+ * Does not fire on a live root (#2103): choudoufu ignores a `backend` block
+ * there (TF024 reports what it still does with it), and the fallback to local
  * state this check warns about does not apply, since a live root keeps no
  * state file at all, local or remote.
  */