@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/pin/source.js

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

package/dist/pin/waves.js

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

package/dist/plan-digest.js

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

package/dist/plugin.js

@@ -0,0 +1,323 @@
+import { terraformBehaviourKinds } from "./behaviour/kinds.js";
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { terraformSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+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 { renderTerraformRoots } from "./hcl/roots.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { auditRootName, LOCK_FILENAME, parseTerraformRootContent, RESOURCE_TYPE } from "./hcl/parse.js";
+import { descendModules } from "./hcl/descend.js";
+import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
+import { terraformCommands } from "./commands.js";
+const loadSkills = createSkillsLoader(import.meta.url, [
+    {
+        file: "chant-terraform.md",
+        name: "chant-terraform",
+        description: "Read an existing Terraform root module into chant's build and audit, and drive it with the init/plan/apply Ops",
+    },
+]);
+/**
+ * The only top-level names Terraform's JSON syntax admits
+ * (developer.hashicorp.com/terraform/language/syntax/json). Used as a
+ * whole-document test in `detectTemplate`: a `.tf.json` file has these keys
+ * and nothing else.
+ */
+const TF_JSON_BLOCK_TYPES = new Set([
+    "terraform",
+    "provider",
+    "variable",
+    "output",
+    "locals",
+    "module",
+    "resource",
+    "data",
+    "moved",
+    "import",
+    "check",
+    "removed",
+]);
+/**
+ * Whether raw text is HCL a Terraform root or module is written in. One
+ * top-level block header is enough, and every one of these headers is
+ * Terraform's own: `terraform {`, and the labelled `resource`/`data`
+ * (two labels), `provider`/`module`/`variable`/`output` (one label). `locals`
+ * is left out on purpose, since it is the one block a non-Terraform HCL
+ * dialect is also likely to carry.
+ */
+function looksLikeHcl(text) {
+    return (/^[ \t]*terraform[ \t]*\{/m.test(text) ||
+        /^[ \t]*(resource|data)[ \t]+"[^"]+"[ \t]+"[^"]+"[ \t]*\{/m.test(text) ||
+        /^[ \t]*(provider|module|variable|output)[ \t]+"[^"]+"[ \t]*\{/m.test(text));
+}
+/**
+ * terraform lexicon plugin.
+ *
+ * There is no upstream schema to pin here: Terraform's resource surface lives
+ * in provider registries, one schema per provider, and this lexicon reads the
+ * HCL an estate already has rather than generating types for it. So `spec/`
+ * and `codegen/` stay near-empty and there is no `upstreamPin`.
+ */
+export const terraformPlugin = {
+    behaviourKinds: terraformBehaviourKinds,
+    name: "terraform",
+    serializer: terraformSerializer,
+    configSchema: terraformConfigSchema,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate } = await import("./codegen/generate.js");
+        await generate(options);
+    },
+    async validate(_options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(_options) {
+        // No upstream spec to measure against. See the note on the plugin.
+        console.error("Coverage analysis not applicable: this lexicon generates no types from an upstream spec");
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    /**
+     * The ownership channel is per mode, and the channel declared here names
+     * the stock one, because a project's roots are stock unless it opts into
+     * choudoufu.
+     *
+     * On a stock root the channel is the state file, not a tag or a label
+     * (#2087): every address `terraform show -json` returns is `owned` and
+     * everything else is `unknown`. On a live root (#2104) it is choudoufu's
+     * two marker tags, `./live-ownership.ts`'s `TERRAFORM_LIVE_MARKER_KEYS`,
+     * and the verdicts come from `live-plan -json`'s own sections. Both
+     * readings resolve a real verdict on this path, which is what declaring
+     * `describeResources` here claims and what the conformance suite checks,
+     * for both modes. See `./describe-resources.ts` and
+     * `docs/pages/observation.mdx`.
+     */
+    ownershipChannel: {
+        keys: TERRAFORM_STATE_OWNERSHIP_KEYS,
+        reads: ["describeResources"],
+    },
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    /**
+     * The prediction, for whichever estate `options.from` names (#2495). The
+     * producer is `predictTerraformBehaviour` and this is its second caller, not
+     * a second producer: the contract's options are read as its own and handed
+     * over, and it runs with the real reads and core's engine front. What that
+     * reading has to put back, for a declared graph and for a live one, is on
+     * `terraformPredictOptionsFrom`.
+     */
+    async predictBehaviour(options) {
+        const { predictTerraformBehaviour, terraformPredictOptionsFrom } = await import("./behaviour/index.js");
+        return predictTerraformBehaviour(await terraformPredictOptionsFrom(options));
+    },
+    /**
+     * The kinds a live root can enumerate beyond its declaration (#1278,
+     * #2104). Empty on a project with no live root, because `live-ls` is the
+     * only estate-wide read this lexicon has and a stock root has none: a state
+     * file knows what it created and nothing else.
+     */
+    ambientKinds() {
+        return [RESOURCE_TYPE];
+    },
+    async observeAmbient(options) {
+        const { observeAmbient } = await import("./describe-resources.js");
+        return observeAmbient(options);
+    },
+    async teardownOwned(options) {
+        const { teardownOwned } = await import("./describe-resources.js");
+        return teardownOwned(options);
+    },
+    /**
+     * Each entry in `terraform.roots` is a root module directory that parses at
+     * build time into one entity per HCL block. The render lives in
+     * `./hcl/roots.ts`; this member only reads the namespace and hands over the
+     * project root, which is what relative `dir` paths resolve against.
+     */
+    async buildRoots(ctx) {
+        const namespace = ctx.config.terraform;
+        const roots = namespace?.roots ?? {};
+        if (Object.keys(roots).length === 0)
+            return { entities: new Map(), warnings: [] };
+        return renderTerraformRoots({
+            projectRoot: ctx.projectRoot,
+            roots,
+            binary: namespace?.binary,
+            callModuleType: namespace?.callModuleType,
+            moduleRoot: namespace?.moduleRoot,
+        });
+    },
+    /** `chant terraform pin-rollout` (#3189). */
+    commands() {
+        return terraformCommands;
+    },
+    /**
+     * The `terraform.roots` a change touched (#3183): a changed file in the
+     * root's directory, in a local module it calls, or one of its var files.
+     * See `./changed-roots.ts`.
+     */
+    async changedUnits(ctx) {
+        const roots = ctx.config.terraform?.roots ?? {};
+        if (Object.keys(roots).length === 0)
+            return [];
+        const { changedRoots } = await import("./changed-roots.js");
+        return changedRoots(ctx.projectRoot, roots, ctx.changedFiles);
+    },
+    lintRules() {
+        return rules;
+    },
+    /**
+     * The generated barrel of checks, each wrapped so a finding inside a
+     * descended child module names the call chain that reached it (#2112). See
+     * `./lint/post-synth/scope.ts`.
+     */
+    postSynthChecks() {
+        return withCallersChain(postSynthChecks);
+    },
+    auditCatalog() {
+        return terraformAuditCatalog;
+    },
+    /**
+     * `recommended`/`all` (chant #2113), the tflint-ruleset-terraform shape:
+     * `recommended` is every `merge-worthy` TF rule (a correctness/security
+     * finding worth reporting by default), `all` adds the `report-only` ones
+     * (hygiene the family grows into as #2109/#2110/#2112 land). Derived from
+     * `terraformAuditCatalog` rather than a hand-kept id list, so a rule that
+     * lands in a later, parallel issue is picked up automatically the moment
+     * its catalog entry ships, with no second list to fall out of sync.
+     */
+    lintPresets() {
+        const ids = Object.keys(terraformAuditCatalog);
+        const recommended = ids.filter((id) => terraformAuditCatalog[id].tier === "merge-worthy");
+        return { recommended, all: ids };
+    },
+    /**
+     * Parse-to-graph for `chant audit` (#1567, #2085, #2217). `content` is the
+     * `# file: <name>`-joined bundle discovery builds for one discovered root
+     * module (`classifyTerraform`, `packages/core/src/audit/discover.ts`), and
+     * `input` says where that bundle came from.
+     *
+     * The scope is named after the input's path (`auditRootName`), so two roots
+     * in one repository are two roots here as well: they no longer collide in
+     * the merged entity map the all-files pass reads, which is what used to
+     * produce a finding keyed `<root>/<address>#2` against the file
+     * `(cross-file)` that neither directory deserved.
+     *
+     * When the audit walked a local filesystem, `input.dir` is the root
+     * module's directory and the parse descends its local `module` calls
+     * exactly as `buildRoots()` does, through the same `descendModules`
+     * (`../hcl/descend.ts`): a child module's entities are keyed
+     * `<root>/module.<name>/<address>` and carry the caller chain, so TF014 and
+     * TF015 fire here with the same `Callers:` line they print on a build, and
+     * the root-only rules (TF001 to TF003) still see only the root's own
+     * blocks. `input.baseDir` is the audited directory, which bounds the
+     * descent the way the project root bounds it on a build. Discovery drops a
+     * directory another one calls as a local module, so no module is audited
+     * twice.
+     *
+     * With no `input.dir` (a fetched repository; a caller parsing a bare
+     * string) the bundle is parsed alone, and the two child-module rules have
+     * no child to report on, since nothing named one.
+     *
+     * The descent's own refusals (a registry source, a source outside the
+     * audited tree, a cycle) are warnings on a build; this hook returns
+     * entities only, so on the audit path they are dropped rather than printed.
+     *
+     * Never throws: malformed HCL yields an empty map.
+     */
+    async auditEntities(content, input) {
+        try {
+            const root = auditRootName(input?.path);
+            // A local audit knows the root's directory, so it can say whether the
+            // lock file is beside the `.tf` files (TF040); a fetched one cannot.
+            const lockFile = input?.dir !== undefined ? existsSync(join(input.dir, LOCK_FILENAME)) : undefined;
+            const entities = await parseTerraformRootContent(content, root, undefined, lockFile === undefined ? undefined : { lockFile });
+            if (input?.dir === undefined)
+                return entities;
+            const { entities: children } = await descendModules(entities, {
+                dir: input.dir,
+                root,
+                projectRoot: input.baseDir ?? input.dir,
+            });
+            for (const [key, entity] of children)
+                entities.set(key, entity);
+            return entities;
+        }
+        catch {
+            return new Map();
+        }
+    },
+    /**
+     * No `mcpTools()` and no `mcpResources()`, deliberately (#2220). Both were
+     * declared returning `[]` behind a TODO, which passed the two tier-2
+     * "registers <method>" checks on a member that contributed nothing. Neither
+     * of the two shapes every other lexicon uses has anything to serve here:
+     * `createDiffTool` diffs one build's serializer output against the last,
+     * and this serializer writes nothing (`src/serializer.ts` is a deliberate
+     * no-op, the `.tf` files are the artifact); `createCatalogResource` serves
+     * the generated resource registry, and this lexicon generates none
+     * (`src/codegen/generate.ts` writes `{}` on purpose). So the members are
+     * removed rather than faked, and `chant dev check-lexicon` reports two
+     * tier-2 gaps that are real.
+     */
+    skills: loadSkills,
+    /**
+     * `.tf` (and Terraform's own JSON syntax, `.tf.json`) recognised by content
+     * rather than by which directory a file sits in (#2220).
+     *
+     * Two input shapes, because the two callers hand over different things.
+     * `chant import` (`packages/core/src/cli/commands/import.ts`) `JSON.parse`s
+     * the file first, so it arrives as an object; the audit's content detection
+     * (`packages/core/src/audit/discover.ts`) hands azure its raw string, and a
+     * `.tf` file is not JSON at all, so the raw string form is the one that
+     * matters for HCL. Anything else reads as false.
+     *
+     * The object form is exact rather than heuristic: Terraform's JSON syntax
+     * admits only the top-level names in {@link TF_JSON_BLOCK_TYPES}, so a
+     * document is `.tf.json` when every key is one of them and at least one is
+     * present. That refuses a Kubernetes manifest, a CloudFormation template and
+     * a Compose file without having to name any of them.
+     *
+     * Discovery still classifies Terraform by the directory bundle
+     * (`classifyTerraform`), because a root module is a directory of files that
+     * has to be parsed together and one `.tf` on its own is not an audit input.
+     * This makes the per-file question answerable for the callers that ask it
+     * one file at a time.
+     */
+    detectTemplate(data) {
+        if (typeof data === "string")
+            return looksLikeHcl(data);
+        if (typeof data !== "object" || data === null || Array.isArray(data))
+            return false;
+        const keys = Object.keys(data);
+        return keys.length > 0 && keys.every((k) => TF_JSON_BLOCK_TYPES.has(k));
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};