@intentius/chant-lexicon-terraform 0.124.31 → 0.124.33

package/dist/pin/rollout.js

@@ -0,0 +1,382 @@
+/**
+ * Roll a module version out as pin-bump pull requests, one wave at a time
+ * (#3189, choudoufu#1749).
+ *
+ * Each run reads where the rollout stands and does at most one thing:
+ *
+ * 1. It checks out the base branch in a temporary worktree and reads every
+ *    root's pin there: at the old version, at the new one, refused (a
+ *    floating constraint, no pin, an expression), or pinned at something
+ *    else. Only roots at the old or the new version are in the rollout, so
+ *    the wave plan is the same on every run.
+ * 2. It splits those roots into waves (`./waves.ts`).
+ * 3. It walks the waves in order, reading each wave's pull request by its
+ *    branch. A wave whose PR merged, and whose every moved root reports its
+ *    apply check as passed on the merge commit, is done. The first wave that
+ *    is not done decides the run:
+ *    - no PR yet: open it (one branch, one PR, the pin moved for that wave's
+ *      roots only), or in `report` mode say it would;
+ *    - PR open, or merged with an apply still pending: report where it
+ *      stands and open nothing;
+ *    - PR closed without merging, or a root whose apply check failed: stop,
+ *      naming it. The waves after it do not open.
+ *
+ * That is #2119's gate as a fact: nothing waits. The next run reads the
+ * forge again and either moves on or reports the same place.
+ *
+ * The PR's branch is built from the base branch in a worktree and pushed.
+ * The default branch, and whatever the caller has checked out, are never
+ * written, as with core's `proposeWorkspaceUpgrade` (#2550). Each PR changes
+ * only the files of its wave's roots, so a path-diff selection (GitLab's
+ * `rules: changes:`, #3183's affected members) plans exactly those roots.
+ *
+ * An "applied" root is one whose apply check, named by `appliedCheck`
+ * (default `apply/{root}`), passed on the merge commit. That is how a
+ * per-root apply job on the merged commit reports today; when the per-PR
+ * loop (#3183) lands, its per-member check name is the one to pass.
+ */
+import { execFile } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, posix } from "node:path";
+import { promisify } from "node:util";
+import { ghHostEnv } from "@intentius/chant/op/activities/gh-host";
+import { editPins } from "./edit.js";
+import { checkPinRequest, moduleOf } from "./source.js";
+import { planPinWaves, restrictWaves, terragruntDependencies } from "./waves.js";
+import { ghPinForge } from "./forge.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`,
+// #3780, #3798): a GitHub Enterprise Server checkout is not sent to github.com.
+const defaultRun = async (bin, args, cwd) => (await execFileAsync(bin, args, { cwd, maxBuffer: 64 * 1024 * 1024, ...(bin === "gh" ? { env: await ghHostEnv(process.env, cwd) } : {}) })).stdout;
+// `.chant` holds work worktrees in `.chant/work`, each a copy of the checkout (chant#2893).
+const SKIP_DIRS = new Set([".git", ".terraform", ".terragrunt-cache", "node_modules", ".chant"]);
+const NO_FORGE = {
+    findPullRequest: async () => null,
+    createPullRequest: async () => {
+        throw new Error("pin rollout: no forge to open a pull request on");
+    },
+    commitChecks: async () => [],
+};
+/** The marker that ties a PR to its wave, and carries the roots it moved. */
+const MARKER = "chant-pin-rollout";
+/** A root directory as the rollout keys it: relative, `/`-separated, no `./` and no trailing slash. */
+function dirOf(path) {
+    return posix.normalize(path.replaceAll("\\", "/")).replace(/\/+$/, "") || ".";
+}
+function slug(value) {
+    const s = value.replace(/^[a-z]+:\/\//, "").replace(/^sha256:([0-9a-f]{12})[0-9a-f]*$/i, "sha256-$1");
+    return s.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
+/** The branch a wave's PR is opened from. */
+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) {
+    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));
+}
+/** Every directory under the worktree with a `.tf` file or a `terragrunt.hcl`. */
+function candidateRoots(worktree) {
+    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")))
+            out.push(rel || ".");
+        for (const e of entries)
+            if (e.isDirectory() && !SKIP_DIRS.has(e.name))
+                walk(rel ? posix.join(rel, e.name) : e.name);
+    };
+    walk("");
+    return out.sort();
+}
+async function editRoot(worktree, root, request, options) {
+    const edits = new Map();
+    const calls = [];
+    let files;
+    if (root.tsSource) {
+        files = [root.tsSource];
+        if (!options.editTs) {
+            return { state: { root: root.root, state: "refused", files, calls, reason: `generated from ${root.tsSource}, and this caller has no TypeScript editor` }, edits };
+        }
+    }
+    else {
+        files = rootFiles(worktree, root.root);
+    }
+    for (const file of files) {
+        const path = join(worktree, file);
+        if (!existsSync(path))
+            return { state: { root: root.root, state: "refused", files, calls, reason: `${file} does not exist on the base branch` }, edits };
+        const text = readFileSync(path, "utf-8");
+        const result = root.tsSource ? options.editTs(text, file, request) : await editPins(text, file, request, options.parser);
+        calls.push(...result.calls);
+        if (result.content !== text)
+            edits.set(file, result.content);
+    }
+    const refused = calls.filter((c) => c.outcome === "refused");
+    let state;
+    let reason;
+    if (calls.length === 0) {
+        state = "absent";
+        reason = "no call of the module";
+    }
+    else if (refused.length > 0) {
+        state = "refused";
+        reason = refused.map((c) => `${c.file} ${c.call}: ${"reason" in c ? c.reason : ""}`).join("; ");
+    }
+    else if (calls.some((c) => c.outcome === "moved")) {
+        state = calls.some((c) => c.outcome === "elsewhere") ? "refused" : "from";
+        if (state === "refused")
+            reason = "some calls are pinned at another version than the old one";
+    }
+    else if (calls.every((c) => c.outcome === "already")) {
+        state = "to";
+    }
+    else {
+        state = "elsewhere";
+        reason = calls.map((c) => ("pin" in c ? `${c.file} ${c.call}: pinned at ${c.pin}` : "")).filter(Boolean).join("; ");
+    }
+    return { state: { root: root.root, state, files, calls, ...(reason ? { reason } : {}) }, edits: state === "from" ? edits : new Map() };
+}
+function parseMarker(body) {
+    const m = new RegExp(`<!-- ${MARKER} (\\{.*?\\}) -->`).exec(body);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+function prBody(request, wave, total, moved, refused, checkName, summary) {
+    const marker = JSON.stringify({ module: request.module, from: request.from, to: request.to, wave: wave.wave, roots: moved.map((r) => r.root) });
+    return [
+        `<!-- ${MARKER} ${marker} -->`,
+        `## Pin bump, wave ${wave.wave} of ${total}${wave.canary ? " (canaries)" : ""}`,
+        "",
+        `\`${request.module}\` pin ${request.from} -> ${request.to}`,
+        "",
+        `Roots in this wave (${moved.length}):`,
+        "",
+        ...moved.map((r) => `- \`${r.root}\`: ${r.calls.filter((c) => c.outcome === "moved").map((c) => `${c.file} ${c.call}`).join(", ")}`),
+        "",
+        "This PR changes only these roots' files, so a path-diff selection plans exactly these roots.",
+        ...(refused.length > 0 ? ["", "Not moved by this rollout:", "", ...refused.map((r) => `- \`${r.root}\`: ${r.reason}`)] : []),
+        ...(summary ? ["", summary] : []),
+        "",
+        wave.wave < total
+            ? `Wave ${wave.wave + 1} opens on a later run, once this PR has merged and each root above reports its apply check (${moved.length > 0 ? `\`${checkName(moved[0].root)}\`` : "none"}${moved.length > 1 ? " and the rest" : ""}) as passed on the merge commit.`
+            : "This is the last wave.",
+        "",
+        "Opened by the terraform lexicon's pin rollout. It never writes the default branch.",
+    ].join("\n");
+}
+async function defaultBranch(run, repo, remote) {
+    try {
+        const ref = (await run("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], repo)).trim();
+        return ref.startsWith(`${remote}/`) ? ref.slice(remote.length + 1) : ref;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read where a rollout stands, and open the next wave's PR when it is due and `mode` is `pull-request`. */
+export async function runPinRollout(options) {
+    const request = { module: moduleOf(options.module), from: options.from, to: options.to };
+    checkPinRequest(request);
+    const mode = options.mode ?? "report";
+    const run = options.run ?? defaultRun;
+    const remote = options.remote ?? "origin";
+    const repo = (await run("git", ["rev-parse", "--show-toplevel"], options.cwd ?? process.cwd())).trim();
+    const checkName = (root) => (options.appliedCheck ?? "apply/{root}").replaceAll("{root}", root);
+    let hasRemote = true;
+    try {
+        await run("git", ["remote", "get-url", remote], repo);
+    }
+    catch {
+        hasRemote = false;
+    }
+    if (mode === "pull-request" && !hasRemote)
+        throw new Error(`pin rollout: no remote "${remote}" to open a pull request on`);
+    // With no remote there is no forge to have opened a PR on, so a report reads every wave as unopened.
+    const forge = options.forge ?? (hasRemote ? ghPinForge(run, repo) : NO_FORGE);
+    if (hasRemote)
+        await run("git", ["fetch", "--quiet", remote], repo);
+    const base = options.base ?? (hasRemote ? await defaultBranch(run, repo, remote) : null) ?? (await run("git", ["symbolic-ref", "--short", "HEAD"], repo)).trim();
+    const baseRef = hasRemote ? `refs/remotes/${remote}/${base}` : `refs/heads/${base}`;
+    const worktree = mkdtempSync(join(tmpdir(), "chant-pin-"));
+    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) => ({
+            ...r,
+            root: dirOf(r.root),
+            ...(r.dependsOn ? { dependsOn: r.dependsOn.map(dirOf) } : {}),
+        }));
+        const roots = [];
+        const edits = new Map();
+        const byRoot = new Map();
+        for (const root of declared) {
+            const { state, edits: e } = await editRoot(worktree, root, request, options);
+            if (options.roots || state.state !== "absent")
+                roots.push(state);
+            edits.set(root.root, e);
+            byRoot.set(root.root, root);
+        }
+        const inRollout = roots.filter((r) => r.state === "from" || r.state === "to");
+        const outside = roots.filter((r) => !(r.state === "from" || r.state === "to"));
+        // 2. The waves, over the roots at the old or the new pin.
+        const keep = new Set(inRollout.map((r) => r.root));
+        let waves;
+        if (options.waves) {
+            waves = restrictWaves(options.waves, keep);
+            const planned = new Set(waves.flatMap((w) => w.roots));
+            const missing = [...keep].filter((r) => !planned.has(r));
+            if (missing.length > 0)
+                throw new Error(`pin rollout: the wave plan does not place ${missing.join(", ")}`);
+        }
+        else {
+            const withDeps = [];
+            for (const r of inRollout) {
+                const declaredRoot = byRoot.get(r.root);
+                const tg = join(worktree, r.root, "terragrunt.hcl");
+                const fromTg = !declaredRoot.tsSource && existsSync(tg) && statSync(tg).isFile() ? await terragruntDependencies(r.root, readFileSync(tg, "utf-8"), options.parser) : [];
+                withDeps.push({ ...declaredRoot, dependsOn: [...new Set([...(declaredRoot.dependsOn ?? []), ...fromTg])] });
+            }
+            // A canary that is a root but out of the rollout (refused, say) is dropped; one that is no root at all is refused by the planner.
+            const canaries = (options.canaries ?? []).map(dirOf);
+            waves = planPinWaves(withDeps, canaries.filter((c) => keep.has(c) || !roots.some((r) => r.root === c)));
+        }
+        // 3. Walk the waves.
+        const statuses = waves.map((w) => ({ ...w, branch: pinWaveBranch(request, w.wave), state: "not-reached" }));
+        let status = "complete";
+        let stop;
+        for (const wave of statuses) {
+            if (wave.branch === base)
+                throw new Error(`pin rollout will not write the base branch "${base}"`);
+            const pr = await forge.findPullRequest(wave.branch);
+            if (pr)
+                wave.pr = pr.url;
+            if (pr?.state === "open") {
+                wave.state = "open";
+                status = "waiting";
+                break;
+            }
+            if (pr?.state === "closed") {
+                wave.state = "closed";
+                status = "stopped";
+                stop = `wave ${wave.wave}'s PR ${pr.url} was closed without merging`;
+                break;
+            }
+            if (pr?.state === "merged") {
+                const moved = parseMarker(pr.body)?.roots ?? wave.roots;
+                const checks = pr.mergeCommit ? await forge.commitChecks(pr.mergeCommit) : [];
+                const stateOf = (root) => checks.find((c) => c.name === checkName(root))?.state ?? "pending";
+                wave.failed = moved.filter((r) => stateOf(r) === "failure");
+                wave.pending = moved.filter((r) => stateOf(r) === "pending");
+                if (wave.failed.length > 0) {
+                    wave.state = "failed";
+                    status = "stopped";
+                    stop = `wave ${wave.wave}: ${wave.failed.map((r) => `${r} failed its apply check ${checkName(r)}`).join(", ")}`;
+                    break;
+                }
+                if (wave.pending.length > 0) {
+                    wave.state = "waiting-apply";
+                    status = "waiting";
+                    break;
+                }
+                wave.state = "applied";
+                continue;
+            }
+            // No PR yet: this wave is next.
+            const moving = roots.filter((r) => wave.roots.includes(r.root) && r.state === "from");
+            if (moving.length === 0) {
+                wave.state = "nothing-to-move";
+                continue;
+            }
+            const files = moving.flatMap((r) => [...edits.get(r.root).keys()]).sort();
+            wave.files = files;
+            if (mode === "report") {
+                wave.state = "would-open";
+                status = "would-open";
+                break;
+            }
+            for (const r of moving)
+                for (const [file, content] of edits.get(r.root))
+                    writeFileSync(join(worktree, file), content);
+            const title = `chore(pin): ${request.module} ${request.from} -> ${request.to}, wave ${wave.wave} of ${statuses.length}`;
+            const summary = options.planSummary ? await options.planSummary(wave) : undefined;
+            const body = prBody(request, wave, statuses.length, moving, outside, checkName, summary);
+            await run("git", ["add", "--", ...files], worktree);
+            const identity = [];
+            const has = async (key) => {
+                try {
+                    return (await run("git", ["config", key], worktree)).trim().length > 0;
+                }
+                catch {
+                    return false;
+                }
+            };
+            if (!(await has("user.name")))
+                identity.push("-c", "user.name=chant");
+            if (!(await has("user.email")))
+                identity.push("-c", "user.email=chant@localhost");
+            await run("git", [...identity, "commit", "--quiet", "--no-verify", "-m", `${title}\n\nRoots: ${moving.map((r) => r.root).join(", ")}\n`], worktree);
+            // The branch is rebuilt from the base branch on every run that opens it, so it is replaced.
+            await run("git", ["push", "--quiet", "--force", remote, `HEAD:refs/heads/${wave.branch}`], worktree);
+            wave.pr = await forge.createPullRequest({ base, head: wave.branch, title, body });
+            wave.state = "opened";
+            status = "opened";
+            break;
+        }
+        if (statuses.length === 0)
+            status = "complete";
+        const result = { ...request, mode, base, status, roots, waves: statuses, ...(stop ? { stop } : {}), summary: "" };
+        result.summary = renderPinRollout(result);
+        return result;
+    }
+    finally {
+        try {
+            await run("git", ["worktree", "remove", "--force", worktree], repo);
+        }
+        catch {
+            rmSync(worktree, { recursive: true, force: true });
+        }
+    }
+}
+const WAVE_TEXT = {
+    applied: "merged and applied",
+    "nothing-to-move": "nothing to move",
+    opened: "PR opened",
+    "would-open": "next; would open its PR",
+    open: "PR open, waiting for merge",
+    "waiting-apply": "merged, waiting for apply",
+    failed: "merged, apply failed",
+    closed: "PR closed without merging",
+    "not-reached": "not opened",
+};
+/** The rollout for a terminal or a run log. */
+export function renderPinRollout(result) {
+    const lines = [`${result.module} pin ${result.from} -> ${result.to} on ${result.base}: ${result.status}${result.stop ? ` (${result.stop})` : ""}`];
+    for (const w of result.waves) {
+        lines.push(`  wave ${w.wave}${w.canary ? " (canaries)" : ""}: ${WAVE_TEXT[w.state]}${w.pr ? ` ${w.pr}` : ""}`);
+        lines.push(`    roots: ${w.roots.join(", ")}`);
+        if (w.pending?.length)
+            lines.push(`    apply pending: ${w.pending.join(", ")}`);
+        if (w.failed?.length)
+            lines.push(`    apply failed: ${w.failed.join(", ")}`);
+        if (w.files?.length)
+            lines.push(`    files: ${w.files.join(", ")}`);
+    }
+    for (const r of result.roots.filter((r) => r.state !== "from" && r.state !== "to"))
+        lines.push(`  not in the rollout: ${r.root}: ${r.reason ?? r.state}`);
+    return lines.join("\n");
+}

package/dist/pin/scan.js

@@ -0,0 +1,287 @@
+/**
+ * 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.
+ */
+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, message) {
+        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, i, file) {
+    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, i, file) {
+    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, file) {
+    const tokens = [];
+    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, file) {
+    const tokens = tokenize(text, file);
+    const blocks = [];
+    let i = 0;
+    const atStatementStart = (k) => k === 0 || tokens[k - 1].kind === "newline" || (tokens[k - 1].kind === "punct" && tokens[k - 1].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 = [];
+        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, i) {
+    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, open, file) {
+    const attributes = [];
+    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) {
+    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) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\$\{/g, "$${").replace(/%\{/g, "%%{");
+}