@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

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;
+  }
+}

package/src/registry/deprecated.test.ts

@@ -0,0 +1,139 @@
+/**
+ * The deprecated-version check against a fixture catalog, the catalog reader
+ * with the registry's token (chant#4599), and the handler's page types.
+ */
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { buildReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import type { ReleaseRecord } from "@intentius/chant/lifecycle/release-ledger";
+import { moduleConsumers } from "../pin/consumers";
+import { catalogUrl, readRegistryCatalog } from "./catalog-read";
+import { deprecatedPins } from "./deprecated";
+import { registryContentType, registryHandler } from "./handler";
+import { RegistryError } from "./reader";
+
+const REPO = join(import.meta.dirname, "..", "pin", "__fixtures__", "consumers");
+
+const rec = (releaseVersion: string, digest: string, timestamp: string): ReleaseRecord => ({
+  version: 1,
+  component: "acme/vpc/aws",
+  env: "registry",
+  digest,
+  releaseVersion,
+  gitSha: "a".repeat(40),
+  runId: "r",
+  timestamp,
+  actor: "ci",
+});
+
+const catalog = buildReleaseCatalog(
+  {
+    releases: [rec("1.0.0", "sha256:v1", "2026-10-01T00:00:00.000Z"), rec("1.1.0", "sha256:v11", "2026-10-02T00:00:00.000Z"), rec("2.0.0", "sha256:v2", "2026-10-03T00:00:00.000Z")],
+    statuses: [
+      { component: "acme/vpc/aws", digest: "sha256:v1", status: "deprecated", reason: "drops flow logs", replacement: "1.1.0", actor: "ana", timestamp: "2026-10-04T00:00:00.000Z" },
+      { component: "acme/vpc/aws", digest: "sha256:v2", status: "yanked", reason: "breaks routes", replacement: "1.1.0", actor: "ana", timestamp: "2026-10-04T00:00:00.000Z" },
+    ],
+    fields: [{ component: "acme/vpc/aws", engine: "terraform", fields: { address: "registry.acme.dev/acme/vpc/aws" } }],
+  },
+  { generatedAt: "2026-10-27T00:00:00.000Z" },
+);
+
+describe("deprecatedPins", () => {
+  test("warns on a deprecated pin, refuses a yanked one, and passes an active one", async () => {
+    const consumers = await moduleConsumers(REPO, ["live/prod", "live/dev", "units/vpc"]);
+    const { warnings, refusals } = deprecatedPins(consumers, catalog);
+    expect(warnings.map((w) => [w.consumer.root, w.version, w.replacement])).toEqual([["live/prod", "1.0.0", "1.1.0"]]);
+    expect(warnings[0]!.message).toBe("live/prod/main.tf module.vpc pins acme/vpc/aws 1.0.0, which is deprecated: drops flow logs; move to 1.1.0");
+    // live/dev pins v2.0.0: the leading v is ignored, and its host's case too.
+    expect(refusals.map((r) => [r.consumer.root, r.version, r.status])).toEqual([["live/dev", "2.0.0", "yanked"]]);
+    expect(refusals[0]!.message).toContain("which is yanked: breaks routes; move to 1.1.0");
+  });
+
+  test("leaves unpinned calls and modules the catalog does not list alone", async () => {
+    const consumers = await moduleConsumers(REPO, ["live/prod"]);
+    const { warnings, refusals } = deprecatedPins(consumers.filter((c) => c.address !== "module.vpc"), catalog);
+    expect(warnings).toEqual([]);
+    expect(refusals).toEqual([]);
+  });
+
+  test("matches a component by name when it has no terraform address, and a pin by digest", () => {
+    const byName = buildReleaseCatalog(
+      {
+        releases: [{ ...rec("3.1.0", "sha256:c31", "2026-10-01T00:00:00.000Z"), component: "oci://registry.acme.dev/modules/cache", releaseVersion: undefined }],
+        statuses: [{ component: "oci://registry.acme.dev/modules/cache", digest: "sha256:c31", status: "yanked", actor: "a", timestamp: "2026-10-02T00:00:00.000Z" }],
+      },
+      { generatedAt: "2026-10-27T00:00:00.000Z" },
+    );
+    const call = { root: "r", file: "r/main.tf", address: "module.cache", kind: "terraform" as const, source: "oci://registry.acme.dev/modules/cache?digest=sha256:c31", module: "oci://registry.acme.dev/modules/cache", pin: "sha256:c31", at: "source" as const, param: "digest" as const };
+    const { refusals } = deprecatedPins([call], byName);
+    expect(refusals.map((r) => [r.version, r.reason])).toEqual([["sha256:c31", null]]);
+    expect(refusals[0]!.message).toBe("r/main.tf module.cache pins oci://registry.acme.dev/modules/cache sha256:c31, which is yanked");
+  });
+});
+
+describe("readRegistryCatalog", () => {
+  const body = JSON.stringify(catalog);
+
+  test("sends the registry's token and validates the answer", async () => {
+    const seen: Array<{ url: string; auth: string | null }> = [];
+    const got = await readRegistryCatalog("modules.acme.dev", {
+      token: "t0k",
+      fetch: async (url, init) => {
+        seen.push({ url, auth: new Headers(init?.headers).get("authorization") });
+        return new Response(body, { status: 200, headers: { "content-type": "application/json" } });
+      },
+    });
+    expect(seen).toEqual([{ url: "https://modules.acme.dev/catalog/index.json", auth: "Bearer t0k" }]);
+    expect(got).toEqual(catalog);
+  });
+
+  test("reads the token the CLIs would send", async () => {
+    let auth: string | null = null;
+    await readRegistryCatalog("modules.acme.dev", {
+      credentials: { env: { TF_TOKEN_modules_acme_dev: "from-env" } },
+      fetch: async (_url, init) => ((auth = new Headers(init?.headers).get("authorization")), new Response(body)),
+    });
+    expect(auth).toBe("Bearer from-env");
+  });
+
+  test("a registry with no catalog gives null; a refusal names where the token goes and never a value", async () => {
+    expect(await readRegistryCatalog("https://cdn.acme.dev/registry", { token: false, fetch: async () => new Response("", { status: 404 }) })).toBeNull();
+    const refused = readRegistryCatalog("modules.acme.dev", { token: false, fetch: async () => new Response("", { status: 401 }) });
+    await expect(refused).rejects.toBeInstanceOf(RegistryError);
+    await expect(readRegistryCatalog("modules.acme.dev", { token: "secret-value", fetch: async () => new Response("", { status: 403 }) })).rejects.toThrow(/refused the token for modules\.acme\.dev/);
+    await expect(readRegistryCatalog("modules.acme.dev", { token: "secret-value", fetch: async () => new Response("", { status: 403 }) })).rejects.not.toThrow(/secret-value/);
+  });
+
+  test("an answer that is not a catalog is an error", async () => {
+    await expect(readRegistryCatalog("modules.acme.dev", { token: false, fetch: async () => new Response("{\"contract\":1}") })).rejects.toThrow(/is not a release catalog/);
+  });
+
+  test("catalogUrl takes a host or a base URL", () => {
+    expect(catalogUrl("modules.acme.dev")).toBe("https://modules.acme.dev/catalog/index.json");
+    expect(catalogUrl("https://cdn.acme.dev/registry")).toBe("https://cdn.acme.dev/registry/catalog/index.json");
+    expect(catalogUrl("localhost:8080", "http")).toBe("http://localhost:8080/catalog/index.json");
+  });
+});
+
+describe("the handler serves catalog pages so a browser renders them", () => {
+  test.each([
+    ["catalog/index.html", "text/html; charset=utf-8"],
+    ["catalog/style.css", "text/css; charset=utf-8"],
+    ["catalog/search.js", "text/javascript; charset=utf-8"],
+    ["catalog/logo.SVG", "image/svg+xml"],
+    ["catalog/index.json", "application/json"],
+    ["v1/modules/acme/vpc/aws/versions", "application/json"],
+    ["vpc-1.0.0.tar.gz", "application/gzip"],
+    ["catalog.d/README", "application/octet-stream"],
+    ["providers/x.zip", "application/octet-stream"],
+  ])("%s is %s", (key, type) => {
+    expect(registryContentType(key)).toBe(type);
+  });
+
+  test("on a request", async () => {
+    const handler = registryHandler(async (key) => (key === "catalog/index.html" ? { body: "<!doctype html>" } : {}));
+    const res = await handler(new Request("https://modules.acme.dev/catalog/index.html"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+  });
+});

package/src/registry/deprecated.ts

@@ -0,0 +1,76 @@
+/**
+ * The deprecated-version check (chant#4599, terragucci#1289 bundle B): each
+ * module call (`moduleConsumers`, ../pin/consumers.ts) against the release
+ * catalog (`readRegistryCatalog`, ./catalog-read.ts). A call pinned to a
+ * deprecated version gets a warning, and one pinned to a yanked version a
+ * refusal, each naming the reason and the version to move to when the
+ * catalog has one.
+ *
+ * A catalog component is matched by the module address its `terraform`
+ * fields name (`terraformCatalogFields`, ./docs.ts), else by its name, both
+ * normalised as the scan normalises a call's source. A call's pin is matched
+ * to a version by the version (a leading `v` ignored) or by the digest. A
+ * call with no pin, or one naming a module or version the catalog does not
+ * list, is left alone: this check speaks only for what the catalog says.
+ */
+import type { CatalogComponent, CatalogVersion, ReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import { normalizeModuleSource, type ModuleConsumer } from "../pin/consumers";
+
+/** One call on a version the catalog marks. */
+export interface DeprecatedPin {
+  consumer: ModuleConsumer;
+  component: string;
+  /** The version as the catalog lists it (its version, or its digest when it has none). */
+  version: string;
+  status: "deprecated" | "yanked";
+  reason: string | null;
+  replacement: string | null;
+  /** One line for a person: where, what, why, and what to move to. */
+  message: string;
+}
+
+/** The check's result: warnings for deprecated pins, refusals for yanked ones. */
+export interface DeprecatedPinsResult {
+  warnings: DeprecatedPin[];
+  refusals: DeprecatedPin[];
+}
+
+const bare = (v: string): string => v.replace(/^v(?=\d)/, "");
+
+function addressOf(c: CatalogComponent): string {
+  const tf = c.fields.terraform as { address?: unknown } | undefined;
+  return normalizeModuleSource(typeof tf?.address === "string" ? tf.address : c.name);
+}
+
+function versionFor(c: CatalogComponent, pin: string): CatalogVersion | undefined {
+  return c.versions.find((v) => (v.version !== null && bare(v.version) === bare(pin)) || v.digest === pin);
+}
+
+/** Check every call against the catalog. */
+export function deprecatedPins(consumers: readonly ModuleConsumer[], catalog: ReleaseCatalog): DeprecatedPinsResult {
+  const byAddress = new Map<string, CatalogComponent>();
+  for (const c of catalog.components) byAddress.set(addressOf(c), c);
+  const out: DeprecatedPinsResult = { warnings: [], refusals: [] };
+  for (const consumer of consumers) {
+    if (consumer.pin === null) continue;
+    const component = byAddress.get(consumer.module);
+    if (!component) continue;
+    const v = versionFor(component, consumer.pin);
+    if (!v || v.status.state === "active") continue;
+    const version = v.version ?? v.digest;
+    const said = [`${consumer.file} ${consumer.address} pins ${component.name} ${version}, which is ${v.status.state}`];
+    if (v.status.reason) said.push(`: ${v.status.reason}`);
+    if (v.status.replacement) said.push(`; move to ${v.status.replacement}`);
+    const finding: DeprecatedPin = {
+      consumer,
+      component: component.name,
+      version,
+      status: v.status.state,
+      reason: v.status.reason,
+      replacement: v.status.replacement,
+      message: said.join(""),
+    };
+    (v.status.state === "yanked" ? out.refusals : out.warnings).push(finding);
+  }
+  return out;
+}

package/src/registry/docs.test.ts

@@ -0,0 +1,140 @@
+/**
+ * The module docs extractor (chant#4598): a module without a terraform-docs
+ * config, one with it (runner faked: found, no binary, failing, and no
+ * runner at all), one written as `.tf.json`, and one with `examples/`; then
+ * the catalog fields and site sections built from them.
+ */
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { buildReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import { renderCatalogSite } from "@intentius/chant/lifecycle/release-catalog-site";
+import { moduleDocs, terraformCatalogFields, terraformCatalogSections, type TerraformDocsRunner } from "./docs";
+
+const FIXTURES = join(import.meta.dirname, "__fixtures__", "docs");
+
+describe("moduleDocs without a terraform-docs config", () => {
+  test("reads inputs, outputs, providers and the README from the HCL", async () => {
+    const docs = await moduleDocs(join(FIXTURES, "vpc"));
+    expect(docs.docsFrom).toBe("hcl");
+    expect(docs.config).toBeNull();
+    expect(docs.note).toBeNull();
+    expect(docs.markdown).toBeNull();
+    expect(docs.readme).toContain("A VPC with flow logs.");
+    expect(docs.inputs).toEqual([
+      { name: "cidr", type: "string", required: true, description: "The VPC's IPv4 CIDR block.", sensitive: false, file: "variables.tf" },
+      { name: "flow_log_key", type: "string", required: false, description: null, sensitive: true, file: "variables.tf" },
+      { name: "tags", type: "map(string)", required: false, default: {}, description: "Tags for every resource.", sensitive: false, file: "variables.tf" },
+    ]);
+    expect(docs.outputs).toEqual([
+      { name: "arn", description: null, sensitive: true, file: "outputs.tf" },
+      { name: "vpc_id", description: "The VPC's id.", sensitive: false, file: "outputs.tf" },
+    ]);
+    expect(docs.providers).toEqual([{ name: "aws", source: "hashicorp/aws", version: ">= 5.0" }]);
+    expect(docs.requiredVersion).toBe(">= 1.5");
+  });
+
+  test("never carries a sensitive default", async () => {
+    const docs = await moduleDocs(join(FIXTURES, "vpc"));
+    expect(JSON.stringify(docs)).not.toContain("not-a-real-key");
+  });
+
+  test("a runner is not called when the module has no config", async () => {
+    let called = false;
+    const docs = await moduleDocs(join(FIXTURES, "vpc"), { terraformDocs: async () => ((called = true), "x") });
+    expect(called).toBe(false);
+    expect(docs.docsFrom).toBe("hcl");
+  });
+});
+
+describe("moduleDocs with examples/", () => {
+  test("lists each example with its README and files", async () => {
+    const docs = await moduleDocs(join(FIXTURES, "vpc"));
+    expect(docs.examples).toEqual([
+      { name: "complete", path: "examples/complete", readme: null, files: ["main.tf"] },
+      { name: "simple", path: "examples/simple", readme: "# Simple\n", files: ["main.tf"] },
+    ]);
+  });
+});
+
+describe("moduleDocs with a .terraform-docs.yml", () => {
+  const dir = join(FIXTURES, "documented");
+
+  test("runs terraform-docs with that file and keeps its markdown", async () => {
+    const calls: Array<{ dir: string; config: string }> = [];
+    const runner: TerraformDocsRunner = async (args) => {
+      calls.push(args);
+      return "## Inputs\n\n| Name | Type |\n|---|---|\n| name | string |\n";
+    };
+    const docs = await moduleDocs(dir, { terraformDocs: runner });
+    expect(calls).toEqual([{ dir, config: ".terraform-docs.yml" }]);
+    expect(docs.docsFrom).toBe("terraform-docs");
+    expect(docs.markdown).toContain("| name | string |");
+    expect(docs.config).toBe(".terraform-docs.yml");
+    expect(docs.inputs.map((i) => i.name)).toEqual(["name"]);
+  });
+
+  test("falls back to the HCL when the binary is missing, and says so", async () => {
+    const docs = await moduleDocs(dir, { terraformDocs: async () => null });
+    expect(docs.docsFrom).toBe("hcl");
+    expect(docs.markdown).toBeNull();
+    expect(docs.note).toBe(".terraform-docs.yml found, and no terraform-docs binary is installed");
+    expect(docs.inputs.map((i) => i.name)).toEqual(["name"]);
+  });
+
+  test("falls back when the runner fails", async () => {
+    const docs = await moduleDocs(dir, { terraformDocs: async () => { throw new Error("exit 1: bad config\nmore"); } });
+    expect(docs.docsFrom).toBe("hcl");
+    expect(docs.note).toBe("terraform-docs failed with .terraform-docs.yml: exit 1: bad config");
+  });
+
+  test("falls back when no runner is given", async () => {
+    const docs = await moduleDocs(dir);
+    expect(docs.docsFrom).toBe("hcl");
+    expect(docs.note).toBe(".terraform-docs.yml found, and no terraform-docs runner was given");
+  });
+});
+
+describe("moduleDocs on .tf.json files", () => {
+  test("reads the JSON syntax the same way", async () => {
+    const docs = await moduleDocs(join(FIXTURES, "json"));
+    expect(docs.inputs).toEqual([
+      { name: "project", type: "string", required: true, description: "The project id.", sensitive: false, file: "main.tf.json" },
+      { name: "region", type: "string", required: false, default: "us-central1", description: null, sensitive: false, file: "main.tf.json" },
+    ]);
+    expect(docs.outputs).toEqual([{ name: "name", description: "The project id, echoed.", sensitive: false, file: "main.tf.json" }]);
+    expect(docs.providers).toEqual([{ name: "google", source: "hashicorp/google", version: "~> 6.0" }]);
+    expect(docs.readme).toBeNull();
+    expect(docs.examples).toEqual([]);
+  });
+});
+
+describe("terraformCatalogFields and terraformCatalogSections", () => {
+  test("fill the catalog's terraform key and render on the version page", async () => {
+    const docs = await moduleDocs(join(FIXTURES, "vpc"));
+    const address = "registry.acme.dev/acme/vpc/aws";
+    const fields = terraformCatalogFields(docs, address);
+    expect(fields).toMatchObject({ address, docsFrom: "hcl", requiredVersion: ">= 1.5" });
+    expect((fields.inputs as Array<Record<string, unknown>>)[0]).not.toHaveProperty("file");
+
+    const catalog = buildReleaseCatalog(
+      {
+        releases: [{ version: 1, component: "acme/vpc/aws", env: "registry", digest: "sha256:v1", releaseVersion: "1.2.0", gitSha: "a".repeat(40), runId: "r", timestamp: "2026-10-01T00:00:00.000Z", actor: "ci" }],
+        fields: [
+          { component: "acme/vpc/aws", engine: "terraform", fields: { address } },
+          { component: "acme/vpc/aws", version: "1.2.0", engine: "terraform", fields },
+        ],
+      },
+      { generatedAt: "2026-10-27T00:00:00.000Z" },
+    );
+    const files = renderCatalogSite(catalog, terraformCatalogSections());
+    const page = new TextDecoder().decode(files.find((f) => f.path === "acme/vpc/aws/1.2.0/index.html")!.bytes);
+    expect(page).toContain("<h2>Inputs</h2>");
+    expect(page).toContain("<td>tags</td><td>map(string)</td><td>{}</td><td>no</td>");
+    expect(page).toContain("<td>flow_log_key</td><td>string</td><td>(sensitive)</td>");
+    expect(page).toContain("version = &quot;1.2.0&quot;");
+    expect(page).toContain("<h2>Requirements</h2>");
+    expect(page).toContain("<td>hashicorp/aws</td>");
+    const component = new TextDecoder().decode(files.find((f) => f.path === "acme/vpc/aws/index.html")!.bytes);
+    expect(component).toContain("source  = &quot;registry.acme.dev/acme/vpc/aws&quot;");
+  });
+});