@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

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

package/src/registry/docs.ts

@@ -0,0 +1,299 @@
+/**
+ * The module docs extractor (chant#4598, terragucci#1289 bundle B): what a
+ * module's catalog page shows, read from the module's own directory.
+ *
+ * {@link moduleDocs} returns the README, the inputs (type, default,
+ * description, sensitivity, whether one is required), the outputs, the
+ * required providers and Terraform version, and the `examples/` tree. The
+ * structured fields always come from chant's own HCL parse
+ * (`parseTerraformRootDir`, ../hcl/parse.ts), `.tf` and `.tf.json` alike.
+ *
+ * When the module carries a `.terraform-docs.yml` (or `.terraform-docs.yaml`)
+ * and the caller passes a terraform-docs runner, the runner is called with
+ * that file and its markdown is kept as the page's body, since the module's
+ * author chose that layout. Without the file, without a runner, or when the
+ * runner finds no binary or fails, the page is built from the parse alone.
+ * `docsFrom` says which happened and `note` says why.
+ *
+ * {@link terraformCatalogFields} turns the docs into the release catalog's
+ * `terraform` fields (`@intentius/chant/lifecycle/release-catalog`), and
+ * {@link terraformCatalogSections} into the site's sections for a component
+ * and a version.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import type { CatalogSiteSection, CatalogSiteSections } from "@intentius/chant/lifecycle/release-catalog-site";
+import { OUTPUT_TYPE, TERRAFORM_TYPE, VARIABLE_TYPE, listTerraformFiles, parseTerraformRootDir, type TerraformEntity } from "../hcl/parse";
+
+/** The terraform-docs config file names a module may carry, in the order they are looked for. */
+export const TERRAFORM_DOCS_CONFIGS = [".terraform-docs.yml", ".terraform-docs.yaml"] as const;
+
+/** One module input, a `variable` block. */
+export interface ModuleInput {
+  name: string;
+  /** The type constraint as written, `string` or `map(object({...}))`, or null when none is declared. */
+  type: string | null;
+  /** True when the variable has no default. */
+  required: boolean;
+  /** The default as the parse reads it. Absent when required, and when the variable is sensitive. */
+  default?: unknown;
+  description: string | null;
+  sensitive: boolean;
+  /** The file that declares it. */
+  file: string;
+}
+
+/** One module output. */
+export interface ModuleOutput {
+  name: string;
+  description: string | null;
+  sensitive: boolean;
+  file: string;
+}
+
+/** One entry of `required_providers`. */
+export interface ModuleProvider {
+  name: string;
+  source: string | null;
+  version: string | null;
+}
+
+/** One directory under `examples/`. */
+export interface ModuleExample {
+  name: string;
+  /** From the module's directory, `examples/<name>`. */
+  path: string;
+  readme: string | null;
+  /** Its configuration files, sorted. */
+  files: string[];
+}
+
+/** Everything a catalog page shows about one module version. */
+export interface ModuleDocs {
+  readme: string | null;
+  inputs: ModuleInput[];
+  outputs: ModuleOutput[];
+  providers: ModuleProvider[];
+  requiredVersion: string | null;
+  examples: ModuleExample[];
+  /** `terraform-docs` when the body is terraform-docs's markdown, `hcl` when the page is built from the parse alone. */
+  docsFrom: "terraform-docs" | "hcl";
+  /** terraform-docs's output, when `docsFrom` is `terraform-docs`. */
+  markdown: string | null;
+  /** The terraform-docs config file found, from the module's directory. */
+  config: string | null;
+  /** Why the parse was used when a config file was found. */
+  note: string | null;
+}
+
+/**
+ * Runs terraform-docs in `dir` with `config` (a path from `dir`) and returns
+ * its markdown, or null when no terraform-docs binary is installed. Injected,
+ * so a test fakes it and a product chooses how the binary is found.
+ */
+export type TerraformDocsRunner = (args: { dir: string; config: string }) => Promise<string | null>;
+
+export interface ModuleDocsOptions {
+  /** The HCL parser; loaded on first use when absent. */
+  parser?: Hcl2Json;
+  /** Runs terraform-docs when the module has a config file. Without one the parse is used. */
+  terraformDocs?: TerraformDocsRunner;
+  /** The binary the module is written for (`terraform`, `tofu`), which decides the files read. */
+  binary?: string;
+}
+
+const README_NAMES = ["README.md", "readme.md", "Readme.md", "README"];
+
+function readme(dir: string): string | null {
+  for (const name of README_NAMES) {
+    const p = join(dir, name);
+    if (existsSync(p) && statSync(p).isFile()) return readFileSync(p, "utf-8");
+  }
+  return null;
+}
+
+/** `${string}` as hcl2json writes an expression, or `string` as a `.tf.json` file does: the expression either way. */
+function expression(v: unknown): string | null {
+  if (typeof v !== "string") return null;
+  const m = /^\$\{([\s\S]*)\}$/.exec(v.trim());
+  return (m ? m[1]! : v).trim();
+}
+
+const text = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+function firstBody(v: unknown): Record<string, unknown> | undefined {
+  const b = Array.isArray(v) ? v[0] : v;
+  return b && typeof b === "object" && !Array.isArray(b) ? (b as Record<string, unknown>) : undefined;
+}
+
+function providersOf(body: Record<string, unknown>): ModuleProvider[] {
+  const out: ModuleProvider[] = [];
+  const blocks = Array.isArray(body.required_providers) ? body.required_providers : body.required_providers ? [body.required_providers] : [];
+  for (const block of blocks) {
+    if (!block || typeof block !== "object") continue;
+    for (const [name, spec] of Object.entries(block as Record<string, unknown>)) {
+      // A bare string is the old `aws = "~> 4.0"` form: a version with no source.
+      if (typeof spec === "string") {
+        out.push({ name, source: null, version: spec });
+        continue;
+      }
+      const s = firstBody(spec) ?? {};
+      out.push({ name, source: text(s.source), version: text(s.version) });
+    }
+  }
+  return out;
+}
+
+function examples(dir: string, binary: string | undefined): ModuleExample[] {
+  const root = join(dir, "examples");
+  if (!existsSync(root) || !statSync(root).isDirectory()) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort()
+    .map((name) => {
+      const path = join(root, name);
+      return { name, path: `examples/${name}`, readme: readme(path), files: [...listTerraformFiles(path, binary)].sort() };
+    });
+}
+
+async function fromTerraformDocs(dir: string, runner: TerraformDocsRunner | undefined): Promise<Pick<ModuleDocs, "docsFrom" | "markdown" | "config" | "note">> {
+  const config = TERRAFORM_DOCS_CONFIGS.find((name) => existsSync(join(dir, name))) ?? null;
+  if (!config) return { docsFrom: "hcl", markdown: null, config: null, note: null };
+  if (!runner) return { docsFrom: "hcl", markdown: null, config, note: `${config} found, and no terraform-docs runner was given` };
+  try {
+    const markdown = await runner({ dir, config });
+    if (markdown === null) return { docsFrom: "hcl", markdown: null, config, note: `${config} found, and no terraform-docs binary is installed` };
+    return { docsFrom: "terraform-docs", markdown, config, note: null };
+  } catch (e) {
+    return { docsFrom: "hcl", markdown: null, config, note: `terraform-docs failed with ${config}: ${(e as Error).message.split("\n", 1)[0]}` };
+  }
+}
+
+/**
+ * Read one module's docs from `dir`. Throws what the HCL parse throws for a
+ * file it cannot read; a terraform-docs failure is never thrown, it falls
+ * back to the parse and says so in `note`.
+ */
+export async function moduleDocs(dir: string, options: ModuleDocsOptions = {}): Promise<ModuleDocs> {
+  const entities = [...(await parseTerraformRootDir(dir, "module", options.parser, options.binary ? { binary: options.binary } : undefined)).values()] as TerraformEntity[];
+  const inputs: ModuleInput[] = [];
+  const outputs: ModuleOutput[] = [];
+  const providers: ModuleProvider[] = [];
+  let requiredVersion: string | null = null;
+  for (const e of entities) {
+    const { address, body, file } = e.props;
+    if (e.entityType === VARIABLE_TYPE) {
+      const sensitive = body.sensitive === true;
+      const required = !("default" in body);
+      inputs.push({
+        name: address.slice("var.".length),
+        type: expression(body.type),
+        required,
+        ...(!required && !sensitive ? { default: body.default } : {}),
+        description: text(body.description),
+        sensitive,
+        file,
+      });
+    } else if (e.entityType === OUTPUT_TYPE) {
+      outputs.push({ name: address.slice("output.".length), description: text(body.description), sensitive: body.sensitive === true, file });
+    } else if (e.entityType === TERRAFORM_TYPE) {
+      providers.push(...providersOf(body));
+      requiredVersion ??= text(body.required_version);
+    }
+  }
+  inputs.sort((a, b) => a.name.localeCompare(b.name));
+  outputs.sort((a, b) => a.name.localeCompare(b.name));
+  providers.sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    readme: readme(dir),
+    inputs,
+    outputs,
+    providers,
+    requiredVersion,
+    examples: examples(dir, options.binary),
+    ...(await fromTerraformDocs(dir, options.terraformDocs)),
+  };
+}
+
+/**
+ * The release catalog's `terraform` fields for a module version: its
+ * address (`<host>/<namespace>/<name>/<system>`), the docs' structured
+ * parts, and the markdown when terraform-docs wrote it. Everything here is
+ * JSON, as the catalog's schema requires.
+ */
+export function terraformCatalogFields(docs: ModuleDocs, address: string): Record<string, unknown> {
+  return {
+    address,
+    inputs: docs.inputs.map(({ file: _file, ...i }) => i),
+    outputs: docs.outputs.map(({ file: _file, ...o }) => o),
+    providers: docs.providers,
+    requiredVersion: docs.requiredVersion,
+    examples: docs.examples.map((x) => ({ name: x.name, path: x.path, files: x.files })),
+    docsFrom: docs.docsFrom,
+    ...(docs.readme !== null ? { readme: docs.readme } : {}),
+    ...(docs.markdown !== null ? { markdown: docs.markdown } : {}),
+  };
+}
+
+/** The `terraform` fields as the site reads them back from the catalog. */
+interface TerraformFields {
+  address?: string;
+  inputs?: Array<Omit<ModuleInput, "file">>;
+  outputs?: Array<Omit<ModuleOutput, "file">>;
+  providers?: ModuleProvider[];
+  requiredVersion?: string | null;
+  examples?: Array<{ name: string; path: string }>;
+  readme?: string;
+  markdown?: string;
+}
+
+const show = (v: unknown): string => (v === undefined ? "" : typeof v === "string" ? JSON.stringify(v) : JSON.stringify(v) ?? "");
+
+function versionSections(f: TerraformFields, version: string | null): CatalogSiteSection[] {
+  const out: CatalogSiteSection[] = [];
+  if (f.address) {
+    const pin = version ? `\n  version = "${version}"` : "";
+    out.push({ title: "Usage", body: { kind: "code", text: `module "${f.address.split("/").at(-2) ?? "this"}" {\n  source  = "${f.address}"${pin}\n}` } });
+  }
+  if (f.inputs?.length) {
+    out.push({
+      title: "Inputs",
+      body: { kind: "table", columns: ["Name", "Type", "Default", "Required", "Description"], rows: f.inputs.map((i) => [i.name, i.type ?? "", i.sensitive ? "(sensitive)" : i.required ? "" : show(i.default), i.required ? "yes" : "no", i.description ?? ""]) },
+    });
+  }
+  if (f.outputs?.length) {
+    out.push({ title: "Outputs", body: { kind: "table", columns: ["Name", "Description", "Sensitive"], rows: f.outputs.map((o) => [o.name, o.description ?? "", o.sensitive ? "yes" : "no"]) } });
+  }
+  if (f.providers?.length || f.requiredVersion) {
+    const rows = (f.providers ?? []).map((p) => [p.name, p.source ?? "", p.version ?? ""]);
+    if (f.requiredVersion) rows.unshift(["terraform", "", f.requiredVersion]);
+    out.push({ title: "Requirements", body: { kind: "table", columns: ["Name", "Source", "Version"], rows } });
+  }
+  if (f.examples?.length) out.push({ title: "Examples", body: { kind: "table", columns: ["Example", "Path"], rows: f.examples.map((x) => [x.name, x.path]) } });
+  // terraform-docs's markdown is shown as text: the site renders no markdown, and escaping keeps a module's README from writing HTML into the page.
+  const body = f.markdown ?? f.readme;
+  if (body) out.push({ title: f.markdown ? "Documentation" : "README", body: { kind: "code", text: body } });
+  return out;
+}
+
+/**
+ * The site sections (`renderCatalogSite`'s `sections`) for Terraform
+ * modules: usage, inputs, outputs, requirements, examples and the README or
+ * terraform-docs's markdown on each version page, read from the version's
+ * `terraform` fields, and the usage line on the component page from the
+ * component's. A component without `terraform` fields gets none.
+ */
+export function terraformCatalogSections(): CatalogSiteSections {
+  return {
+    component: (c) => {
+      const f = c.fields.terraform as TerraformFields | undefined;
+      return f?.address ? versionSections({ address: f.address }, c.latest && !c.latest.includes(":") ? c.latest : null) : [];
+    },
+    version: (_c, v) => {
+      const f = v.fields.terraform as TerraformFields | undefined;
+      return f ? versionSections(f, v.version) : [];
+    },
+  };
+}