@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/plan-shape.ts

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

package/src/plugin.ts

@@ -1,5 +1,5 @@
-import { lastMemberReport, readPulumiMember, setLastMemberReport } from "./workspace-member";
 import type { AuditEntitiesInput, LexiconPlugin } from "@intentius/chant/lexicon";
+import { terraformCiSetup } from "./ci-setup";
 import { terraformBehaviourKinds } from "./behaviour/kinds";
 import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
 import type { Declarable } from "@intentius/chant/declarable";
@@ -11,7 +11,7 @@ import { withCallersChain } from "./lint/post-synth/scope";
 import { terraformAuditCatalog } from "./lint/audit-catalog";
 import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
-import { terraformConfigSchema, type TerraformConfig } from "./config";
+import { ownRoots, terraformConfigSchema, type TerraformConfig } from "./config";
 import { renderTerraformRoots } from "./hcl/roots";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -20,6 +20,7 @@ import { descendModules } from "./hcl/descend";
 import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership";
 import { terraformCommands } from "./commands";
 import { terraformCapabilityPack } from "./capabilities/adapter";
+import { TERRAFORM_REFERENCE_CATALOG } from "./behaviour/reference-catalog";
 
 const loadSkills = createSkillsLoader(import.meta.url, [
   {
@@ -79,9 +80,16 @@ export const terraformPlugin: LexiconPlugin = {
   behaviourKinds: terraformBehaviourKinds,
   name: "terraform",
   capabilityPack: terraformCapabilityPack,
+  // Keyed by provider type (#2360); see its module doc for which nodes it reads (#4535).
+  referenceCatalog: TERRAFORM_REFERENCE_CATALOG,
   serializer: terraformSerializer,
   configSchema: terraformConfigSchema,
 
+  // #4550: the engine install lines for the pull request pipeline's default image.
+  ciSetup(ctx: { dir: string }): string[] {
+    return terraformCiSetup(ctx);
+  },
+
   // ── Required lifecycle methods ────────────────────────────────
 
   async generate(options?: { verbose?: boolean }): Promise<void> {
@@ -141,6 +149,18 @@ export const terraformPlugin: LexiconPlugin = {
     return describeResources(options);
   },
 
+  /**
+   * Each root's drift, as drift-record stream lines (behold#995): a stock
+   * root through its state or a plan, a live root through `live-plan` (and a
+   * plan), one resource through `live-plan -resource`. `chant workspace
+   * drift` reaches it through `chant lifecycle drift` in a member's reader
+   * project. See `./drift-read.ts`.
+   */
+  async readDrift(options) {
+    const { readTerraformDrift } = await import("./drift-read");
+    return readTerraformDrift(options);
+  },
+
   /**
    * The prediction, for whichever estate `options.from` names (#2495). The
    * producer is `predictTerraformBehaviour` and this is its second caller, not
@@ -181,15 +201,9 @@ export const terraformPlugin: LexiconPlugin = {
    * project root, which is what relative `dir` paths resolve against.
    */
   async buildRoots(ctx): Promise<{ entities: Map<string, Declarable>; warnings: string[] }> {
-    setLastMemberReport(undefined);
     const namespace = (ctx.config as { terraform?: TerraformConfig }).terraform;
-    // A pulumi workspace member (#3179): its checked-in stack export, never the program.
-    if (namespace?.pulumiMember) {
-      const read = readPulumiMember({ member: namespace.pulumiMember });
-      setLastMemberReport(read.report);
-      return { entities: read.entities, warnings: read.warnings };
-    }
-    const roots = namespace?.roots ?? {};
+    // A `signalOnly` root (#4484) feeds change detection only, so it builds no entities here.
+    const roots = ownRoots(namespace?.roots);
     if (Object.keys(roots).length === 0) return { entities: new Map(), warnings: [] };
     return renderTerraformRoots({
       projectRoot: ctx.projectRoot,
@@ -200,11 +214,6 @@ export const terraformPlugin: LexiconPlugin = {
     });
   },
 
-  graphMeta() {
-    const report = lastMemberReport();
-    return report ? { pulumiMember: report } : undefined;
-  },
-
   /** `chant terraform pin-rollout` (#3189). */
   commands() {
     return terraformCommands;
@@ -213,13 +222,15 @@ export const terraformPlugin: LexiconPlugin = {
   /**
    * The `terraform.roots` a change touched (#3183): a changed file in the
    * root's directory, in a local module it calls, or one of its var files.
-   * See `./changed-roots.ts`.
+   * See `./changed-roots.ts`. Every root counts, a `signalOnly` one too
+   * (#4484): that is what it is declared for.
    */
   async changedUnits(ctx) {
-    const roots = (ctx.config as { terraform?: TerraformConfig }).terraform?.roots ?? {};
+    const tf = (ctx.config as { terraform?: TerraformConfig }).terraform;
+    const roots = tf?.roots ?? {};
     if (Object.keys(roots).length === 0) return [];
     const { changedRoots } = await import("./changed-roots");
-    return changedRoots(ctx.projectRoot, roots, ctx.changedFiles);
+    return changedRoots(ctx.projectRoot, roots, ctx.changedFiles, tf?.binary);
   },
 
   lintRules() {
@@ -294,12 +305,21 @@ export const terraformPlugin: LexiconPlugin = {
       // A local audit knows the root's directory, so it can say whether the
       // lock file is beside the `.tf` files (TF040); a fetched one cannot.
       const lockFile = input?.dir !== undefined ? existsSync(join(input.dir, LOCK_FILENAME)) : undefined;
-      const entities = await parseTerraformRootContent(content, root, undefined, lockFile === undefined ? undefined : { lockFile });
+      // An audit has no `terraform.binary` to follow (chant#4457). A root
+      // that carries a `.tofu` file is written for OpenTofu, so it is read
+      // as a tofu root; any other is read as terraform, the config default.
+      const binary = /^# file: .*\.tofu(\.json)?\s*$/m.test(content) ? "tofu" : undefined;
+      const modeOptions = {
+        ...(binary !== undefined ? { binary } : {}),
+        ...(lockFile !== undefined ? { lockFile } : {}),
+      };
+      const entities = await parseTerraformRootContent(content, root, undefined, Object.keys(modeOptions).length > 0 ? modeOptions : undefined);
       if (input?.dir === undefined) return entities;
       const { entities: children } = await descendModules(entities, {
         dir: input.dir,
         root,
         projectRoot: input.baseDir ?? input.dir,
+        ...(binary !== undefined ? { modeOptions: { binary } } : {}),
       });
       for (const [key, entity] of children) entities.set(key, entity);
       return entities;

package/src/registry/__fixtures__/docs/documented/.terraform-docs.yml

@@ -0,0 +1,3 @@
+formatter: markdown table
+output:
+  mode: inject

package/src/registry/__fixtures__/docs/documented/README.md

@@ -0,0 +1 @@
+# documented

package/src/registry/__fixtures__/docs/documented/main.tf

@@ -0,0 +1,8 @@
+variable "name" {
+  type        = string
+  description = "The bucket's name."
+}
+
+output "bucket" {
+  value = var.name
+}

package/src/registry/__fixtures__/docs/json/main.tf.json

@@ -0,0 +1,14 @@
+{
+  "terraform": {
+    "required_providers": {
+      "google": { "source": "hashicorp/google", "version": "~> 6.0" }
+    }
+  },
+  "variable": {
+    "project": { "type": "string", "description": "The project id." },
+    "region": { "type": "string", "default": "us-central1" }
+  },
+  "output": {
+    "name": { "value": "${var.project}", "description": "The project id, echoed." }
+  }
+}

package/src/registry/__fixtures__/docs/vpc/README.md

@@ -0,0 +1,3 @@
+# vpc
+
+A VPC with flow logs.

package/src/registry/__fixtures__/docs/vpc/examples/complete/main.tf

@@ -0,0 +1,5 @@
+module "vpc" {
+  source = "../.."
+  cidr   = "10.1.0.0/16"
+  tags   = { team = "net" }
+}

package/src/registry/__fixtures__/docs/vpc/examples/simple/README.md

@@ -0,0 +1 @@
+# Simple

package/src/registry/__fixtures__/docs/vpc/examples/simple/main.tf

@@ -0,0 +1,4 @@
+module "vpc" {
+  source = "../.."
+  cidr   = "10.0.0.0/16"
+}

package/src/registry/__fixtures__/docs/vpc/main.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.5"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.0"
+    }
+  }
+}
+
+resource "aws_vpc" "this" {
+  cidr_block = var.cidr
+  tags       = var.tags
+}

package/src/registry/__fixtures__/docs/vpc/outputs.tf

@@ -0,0 +1,9 @@
+output "vpc_id" {
+  value       = aws_vpc.this.id
+  description = "The VPC's id."
+}
+
+output "arn" {
+  value     = aws_vpc.this.arn
+  sensitive = true
+}

package/src/registry/__fixtures__/docs/vpc/variables.tf

@@ -0,0 +1,16 @@
+variable "cidr" {
+  type        = string
+  description = "The VPC's IPv4 CIDR block."
+}
+
+variable "tags" {
+  type        = map(string)
+  default     = {}
+  description = "Tags for every resource."
+}
+
+variable "flow_log_key" {
+  type      = string
+  default   = "not-a-real-key"
+  sensitive = true
+}

package/src/registry/__fixtures__/proxied-root/main.tf

@@ -0,0 +1,12 @@
+terraform {
+  required_providers {
+    aws = {
+      source = "acme.jfrog.io/tf-remote__hashicorp/aws"
+    }
+  }
+}
+
+module "vpc" {
+  source  = "acme.jfrog.io/tf-remote__terraform-aws-modules/vpc/aws"
+  version = "5.1.0"
+}

package/src/registry/address.ts

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

package/src/registry/catalog-read.ts

@@ -0,0 +1,56 @@
+/**
+ * Reading a registry's release catalog (chant#4599, terragucci#1289 bundle
+ * B): `catalog/index.json` beside the registry's files, the document
+ * `renderCatalogSite` writes (`@intentius/chant/lifecycle/release-catalog-site`).
+ *
+ * The request carries the token the CLIs would send the host (chant#4563,
+ * `readToken` in ./reader.ts), so a registry behind the edge function's
+ * `auth: token` check answers it. Per ruling B (2026-10-27) this reader is
+ * how a token-protected catalog is read; the edge function gains no cookie
+ * and no open path, and a browser reaches the catalog over the
+ * network-private path.
+ */
+import { credentialsHost, tokenVariable } from "@intentius/chant/terraform/credentials";
+import { parseReleaseCatalog, ReleaseCatalogError, type ReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import { readToken, RegistryError, type RegistryFetch, type RegistryReadOptions } from "./reader";
+
+/** Where the catalog sits under a registry's root. */
+export const CATALOG_PATH = "catalog/index.json";
+
+/** The catalog URL for a registry: a host (`modules.acme.dev`) or a base URL (`https://modules.acme.dev/` or `https://cdn.acme.dev/registry/`). */
+export function catalogUrl(registry: string, scheme: "https" | "http" = "https"): string {
+  const base = registry.includes("://") ? registry : `${scheme}://${registry}`;
+  return new URL(CATALOG_PATH, base.endsWith("/") ? base : `${base}/`).toString();
+}
+
+/**
+ * Fetch and validate a registry's catalog. Throws `RegistryError` when the
+ * request fails or is refused (naming where a token goes, never a value),
+ * and when the answer is not a valid catalog. A registry with no catalog
+ * (404) gives null.
+ */
+export async function readRegistryCatalog(registry: string, options: RegistryReadOptions = {}): Promise<ReleaseCatalog | null> {
+  const url = catalogUrl(registry, options.scheme);
+  const host = new URL(url).host.toLowerCase();
+  const token = readToken(host, options);
+  const fetchFn: RegistryFetch = options.fetch ?? ((u, init) => fetch(u, init));
+  let res: Response;
+  try {
+    res = await fetchFn(url, { method: "GET", redirect: "follow", headers: { Accept: "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) } });
+  } catch (e) {
+    throw new RegistryError(`${url}: ${(e as Error).message}`);
+  }
+  if (res.status === 404) return null;
+  if (res.status === 401 || res.status === 403) {
+    const variable = tokenVariable(host);
+    const where = variable ? `${variable} or a credentials "${credentialsHost(host)}" block` : `a credentials "${credentialsHost(host) ?? host}" block in credentials.tfrc.json`;
+    throw new RegistryError(token ? `${url} answered ${res.status}: the registry refused the token for ${host}` : `${url} answered ${res.status}: the catalog wants a token; set ${where}`);
+  }
+  if (!res.ok) throw new RegistryError(`${url} answered ${res.status}`);
+  try {
+    return parseReleaseCatalog(await res.text());
+  } catch (e) {
+    if (e instanceof ReleaseCatalogError) throw new RegistryError(`${url} is not a release catalog: ${e.problems.slice(0, 3).join("; ")}`);
+    throw e;
+  }
+}