@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/registry/address.js

@@ -0,0 +1,65 @@
+/**
+ * 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}$/;
+/** A module name the protocol cannot carry. */
+export class RegistryNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegistryNameError";
+    }
+}
+/** The host a registry's sources name: its URL without the scheme, lower-cased. */
+export const registryHost = (reg) => 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, rel) {
+    let best;
+    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, rel) {
+    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 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, hosts = []) {
+    const base = source.split("?")[0].split("//")[0];
+    const m = /^([a-z0-9.-]+(?::\d+)?)\/([^/]+)\/([^/]+)\/([^/]+)$/i.exec(base);
+    const known = (h) => 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, path) => {
+    const p = (prefix ?? "").replace(/^\/+|\/+$/g, "");
+    return p ? `${p}/${path}` : path;
+};
+/** The tarball's name beside its version. */
+export const tarballName = (addr, version) => `${addr.name}-${version}.tar.gz`;

package/dist/registry/catalog-read.d.ts

@@ -0,0 +1,14 @@
+import { type ReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import { type RegistryReadOptions } from "./reader.js";
+/** Where the catalog sits under a registry's root. */
+export declare 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 declare function catalogUrl(registry: string, scheme?: "https" | "http"): string;
+/**
+ * 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 declare function readRegistryCatalog(registry: string, options?: RegistryReadOptions): Promise<ReleaseCatalog | null>;
+//# sourceMappingURL=catalog-read.d.ts.map

package/dist/registry/catalog-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-read.d.ts","sourceRoot":"","sources":["../../src/registry/catalog-read.ts"],"names":[],"mappings":"AAaA,OAAO,EAA4C,KAAK,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC3H,OAAO,EAAgD,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAElG,sDAAsD;AACtD,eAAO,MAAM,YAAY,uBAAuB,CAAC;AAEjD,mJAAmJ;AACnJ,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,GAAG,MAAgB,GAAG,MAAM,CAGvF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAwB7H"}

package/dist/registry/catalog-read.js

@@ -0,0 +1,58 @@
+/**
+ * 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 } from "@intentius/chant/lifecycle/release-catalog";
+import { readToken, RegistryError } from "./reader.js";
+/** 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, scheme = "https") {
+    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, options = {}) {
+    const url = catalogUrl(registry, options.scheme);
+    const host = new URL(url).host.toLowerCase();
+    const token = readToken(host, options);
+    const fetchFn = options.fetch ?? ((u, init) => fetch(u, init));
+    let res;
+    try {
+        res = await fetchFn(url, { method: "GET", redirect: "follow", headers: { Accept: "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) } });
+    }
+    catch (e) {
+        throw new RegistryError(`${url}: ${e.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/dist/registry/deprecated.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 { ReleaseCatalog } from "@intentius/chant/lifecycle/release-catalog";
+import { type ModuleConsumer } from "../pin/consumers.js";
+/** 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[];
+}
+/** Check every call against the catalog. */
+export declare function deprecatedPins(consumers: readonly ModuleConsumer[], catalog: ReleaseCatalog): DeprecatedPinsResult;
+//# sourceMappingURL=deprecated.d.ts.map

package/dist/registry/deprecated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecated.d.ts","sourceRoot":"","sources":["../../src/registry/deprecated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAoC,cAAc,EAAE,MAAM,4CAA4C,CAAC;AACnH,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE9E,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,GAAG,QAAQ,CAAC;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAaD,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,oBAAoB,CA0BlH"}

package/dist/registry/deprecated.js

@@ -0,0 +1,43 @@
+import { normalizeModuleSource } from "../pin/consumers.js";
+const bare = (v) => v.replace(/^v(?=\d)/, "");
+function addressOf(c) {
+    const tf = c.fields.terraform;
+    return normalizeModuleSource(typeof tf?.address === "string" ? tf.address : c.name);
+}
+function versionFor(c, pin) {
+    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, catalog) {
+    const byAddress = new Map();
+    for (const c of catalog.components)
+        byAddress.set(addressOf(c), c);
+    const out = { 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 = {
+            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/dist/registry/docs.d.ts

@@ -0,0 +1,96 @@
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import type { CatalogSiteSections } from "@intentius/chant/lifecycle/release-catalog-site";
+/** The terraform-docs config file names a module may carry, in the order they are looked for. */
+export declare const TERRAFORM_DOCS_CONFIGS: readonly [".terraform-docs.yml", ".terraform-docs.yaml"];
+/** 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;
+}
+/**
+ * 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 declare function moduleDocs(dir: string, options?: ModuleDocsOptions): Promise<ModuleDocs>;
+/**
+ * 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 declare function terraformCatalogFields(docs: ModuleDocs, address: string): Record<string, unknown>;
+/**
+ * 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 declare function terraformCatalogSections(): CatalogSiteSections;
+//# sourceMappingURL=docs.d.ts.map

package/dist/registry/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/registry/docs.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,iDAAiD,CAAC;AAG/G,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,YAAI,qBAAqB,EAAE,sBAAsB,CAAU,CAAC;AAE/F,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,mGAAmG;IACnG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,sHAAsH;IACtH,QAAQ,EAAE,gBAAgB,GAAG,KAAK,CAAC;IACnC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEpG,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAuClG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYjG;AA2CD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAW9D"}

package/dist/registry/docs.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { OUTPUT_TYPE, TERRAFORM_TYPE, VARIABLE_TYPE, listTerraformFiles, parseTerraformRootDir } from "../hcl/parse.js";
+/** 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"];
+const README_NAMES = ["README.md", "readme.md", "Readme.md", "README"];
+function readme(dir) {
+    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) {
+    if (typeof v !== "string")
+        return null;
+    const m = /^\$\{([\s\S]*)\}$/.exec(v.trim());
+    return (m ? m[1] : v).trim();
+}
+const text = (v) => (typeof v === "string" ? v : null);
+function firstBody(v) {
+    const b = Array.isArray(v) ? v[0] : v;
+    return b && typeof b === "object" && !Array.isArray(b) ? b : undefined;
+}
+function providersOf(body) {
+    const out = [];
+    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)) {
+            // 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, binary) {
+    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, runner) {
+    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.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, options = {}) {
+    const entities = [...(await parseTerraformRootDir(dir, "module", options.parser, options.binary ? { binary: options.binary } : undefined)).values()];
+    const inputs = [];
+    const outputs = [];
+    const providers = [];
+    let requiredVersion = 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 ?? (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, address) {
+    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 } : {}),
+    };
+}
+const show = (v) => (v === undefined ? "" : typeof v === "string" ? JSON.stringify(v) : JSON.stringify(v) ?? "");
+function versionSections(f, version) {
+    const out = [];
+    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() {
+    return {
+        component: (c) => {
+            const f = c.fields.terraform;
+            return f?.address ? versionSections({ address: f.address }, c.latest && !c.latest.includes(":") ? c.latest : null) : [];
+        },
+        version: (_c, v) => {
+            const f = v.fields.terraform;
+            return f ? versionSections(f, v.version) : [];
+        },
+    };
+}

package/dist/registry/edge/edge.d.ts

@@ -0,0 +1,46 @@
+import { type RegistryFiles } from "../handler.js";
+/** Read auth: the tokens accepted and how tarball URLs are signed. */
+export interface EdgeAuth {
+    /** Accepted bearer tokens. Keep two while one is rotated out. */
+    tokens: string[];
+    /** The key tarball URLs are signed with. Default: the first token. */
+    signingKey?: string;
+    /** Seconds a signed tarball URL works. Default 300. */
+    ttl?: number;
+}
+export interface RegistryEdgeOptions {
+    /** Where the registry's files are read: the bucket behind the function. */
+    files: RegistryFiles;
+    /** The registry's prefix in the bucket. */
+    prefix?: string;
+    /** Read auth. Absent (the default) means anyone who can reach the host reads. */
+    auth?: EdgeAuth;
+    /** Milliseconds since the epoch; a test fixes it. Default `Date.now`. */
+    now?: () => number;
+    /** Called once per request: method, path and the status sent. Never given a token. */
+    log?: (line: string) => void;
+}
+/** The query parameters a signed tarball URL carries. */
+export declare const SIGNED_EXPIRES = "expires";
+export declare const SIGNED_SIGNATURE = "signature";
+/** Default lifetime of a signed tarball URL, in seconds. */
+export declare const DEFAULT_SIGNED_TTL = 300;
+/** A location with `expires` and `signature` added, valid for `ttl` seconds from `nowMs`. */
+export declare function signLocation(location: string, key: string, nowMs: number, ttl?: number): Promise<string>;
+/** Whether a URL carries a signature this key made for its path that has not expired. */
+export declare function verifySignedUrl(url: URL, key: string, nowMs: number): Promise<boolean>;
+/** Whether a request carries one of the accepted bearer tokens. */
+export declare function bearerAccepted(request: Request, tokens: string[]): boolean;
+/**
+ * The part of the function that decides before the bucket is read: a 401, a
+ * download answer, or undefined for "serve this file from the bucket as it is".
+ * Lambda@Edge uses this on its own and lets CloudFront fetch the rest.
+ */
+export declare function registryEdgeGate(options: RegistryEdgeOptions): (request: Request) => Promise<Response | undefined>;
+/** The whole function: the gate, then every other file served from the bucket by `registryHandler`. */
+export declare function registryEdge(options: RegistryEdgeOptions): (request: Request) => Promise<Response>;
+/** Registry files read from an origin over HTTP: a public bucket endpoint, a website endpoint, or a test server. */
+export declare function originFiles(base: string, fetchFn?: (url: string, init?: RequestInit) => Promise<Response>): RegistryFiles;
+/** Accepted tokens from a secret's text: one per line or comma separated, blanks dropped. */
+export declare const tokensFromSecret: (text: string | undefined) => string[];
+//# sourceMappingURL=edge.d.ts.map

package/dist/registry/edge/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../../src/registry/edge/edge.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAIjE,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,KAAK,EAAE,aAAa,CAAC;IACrB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,sFAAsF;IACtF,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,yDAAyD;AACzD,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AA6BtC,6FAA6F;AAC7F,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1H;AAED,yFAAyF;AACzF,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK5F;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAQ1E;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAuClH;AA4BD,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAIlG;AAED,oHAAoH;AACpH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAyB,GAAG,aAAa,CAQhJ;AAED,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,SAAU,MAAM,GAAG,SAAS,KAAG,MAAM,EAAyE,CAAC"}