@intentius/chant-lexicon-terraform 0.124.56 → 0.124.58

package/dist/template/render.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A template request as Terraform files (#4652, epic #4642): a new root for
+ * an app, or one more module call in an app's root for an add-on.
+ *
+ * {@link renderAppRoot} writes `main.tf` with one `module "app"` block. Its
+ * `source` is the template's registry address and its `version` is the
+ * requested version, pinned exactly (`version = "1.2.0"`), which is the form
+ * the pin editor (`../pin/edit.ts`) reads and moves, so a rollout finds the
+ * app. The module's outputs are re-exported as `app_<output>`. Day-2 actions
+ * the template declares are addressed through the call, as
+ * `module.app.action.<type>.<name>`, so nothing is written for them here.
+ *
+ * {@link renderAddonCall} writes `addon-<name>.tf` for the app's own root
+ * (ruling C of #4642) with one `module "<name>"` block. An input whose value
+ * is the string `app.<output>` becomes the reference `module.app.<output>`.
+ *
+ * Each input is written as an HCL literal of its engine-neutral kind
+ * (template.yml/v1, `@intentius/chant/template-request`), in the order the
+ * template lists them, with two-space indent and the `=` signs lined up as
+ * `terraform fmt` lines them up. A sensitive input never travels in a
+ * request: the file declares a sensitive root variable of the kind's
+ * Terraform type ({@link terraformInputType}) and passes `var.<name>`, so
+ * the value comes from the root's own secret store.
+ *
+ * The backend, provider and version files are not written here; the caller
+ * writes them in the same pull request. Nothing here reads the disk, so the
+ * output depends on the arguments alone: the same request gives the same
+ * bytes.
+ */
+import { type TemplateInput, type TemplateRequest } from "@intentius/chant/template-request";
+/** The module block an app root calls its template through. Actions are addressed as `module.app.action...`. */
+export declare const APP_MODULE_NAME = "app";
+/** The prefix of the root outputs an app root re-exports its module's outputs under. */
+export declare const APP_OUTPUT_PREFIX = "app_";
+/** The file an app root's module call is written to. */
+export declare const APP_ROOT_FILE = "main.tf";
+/** The file in the app's root an add-on's module call is written to. */
+export declare function addonFile(name: string): string;
+/** Why a request cannot be rendered. */
+export type TemplateRenderErrorCode = "wrong-kind" | "bad-name" | "not-a-version" | "unknown-input" | "missing-input" | "sensitive-input" | "input-type" | "unknown-output";
+/** Thrown when a request cannot become files. `subject` names the input, output or field at fault. */
+export declare class TemplateRenderError extends Error {
+    readonly code: TemplateRenderErrorCode;
+    readonly subject: string;
+    constructor(code: TemplateRenderErrorCode, subject: string, message: string);
+}
+/** One output of the template's module, as the catalog's `terraform.outputs` lists it. */
+export interface TemplateOutput {
+    name: string;
+    description?: string | null;
+    sensitive?: boolean;
+}
+/** One file to write, its path relative to the app's root directory. */
+export interface RenderedFile {
+    path: string;
+    text: string;
+}
+export interface RenderAppRootOptions {
+    /** A request of kind `app`. */
+    request: TemplateRequest;
+    /** The template's registry address, such as `registry.example.com/acme/orders/aws`. */
+    source: string;
+    /** The template's inputs, from its template.yml, in the order it lists them. */
+    inputs: readonly TemplateInput[];
+    /** The module's outputs, each re-exported as `app_<name>`. */
+    outputs?: readonly TemplateOutput[];
+}
+export interface RenderAddonCallOptions {
+    /** A request of kind `addon`, naming the add-on in `addon`. */
+    request: TemplateRequest;
+    /** The add-on template's registry address. */
+    source: string;
+    /** The add-on template's inputs, from its template.yml, in the order it lists them. */
+    inputs: readonly TemplateInput[];
+    /** The outputs of the app's own module, which `app.<output>` values may name. */
+    appOutputs: readonly (string | TemplateOutput)[];
+}
+/**
+ * The Terraform type an input's kind maps to: `string`, `number`, `bool`,
+ * `list(<of>)`, `map(<of>)`, and `any` for an object or for a list or map
+ * whose element kind is not given (`list(any)`, `map(any)`).
+ */
+export declare function terraformInputType(input: Pick<TemplateInput, "kind" | "of">): string;
+/**
+ * The root of a new app: `main.tf` with one `module "app"` block calling
+ * the template at the requested version, and an `app_<output>` root output
+ * for each of the module's outputs. Throws {@link TemplateRenderError}.
+ */
+export declare function renderAppRoot(options: RenderAppRootOptions): RenderedFile[];
+/**
+ * An add-on's module call for the app's root: `addon-<name>.tf` with one
+ * `module "<name>"` block. A value `app.<output>` becomes
+ * `module.app.<output>`, refused with `unknown-output` when the app module
+ * has no such output. Throws {@link TemplateRenderError}.
+ */
+export declare function renderAddonCall(options: RenderAddonCallOptions): RenderedFile;
+//# sourceMappingURL=render.d.ts.map

package/dist/template/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/template/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAiD,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAI5I,gHAAgH;AAChH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC,wDAAwD;AACxD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wCAAwC;AACxC,MAAM,MAAM,uBAAuB,GAC/B,YAAY,GACZ,UAAU,GACV,eAAe,GACf,eAAe,GACf,eAAe,GACf,iBAAiB,GACjB,YAAY,GACZ,gBAAgB,CAAC;AAErB,sGAAsG;AACtG,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;aAC7B,OAAO,EAAE,MAAM;IAFjC,YACkB,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,MAAM,EAC/B,OAAO,EAAE,MAAM,EAIhB;CACF;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,OAAO,EAAE,eAAe,CAAC;IACzB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,iFAAiF;IACjF,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAYpF;AA2LD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,EAAE,CAgB3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY,CAY7E"}

package/dist/template/render.js

@@ -0,0 +1,276 @@
+/**
+ * A template request as Terraform files (#4652, epic #4642): a new root for
+ * an app, or one more module call in an app's root for an add-on.
+ *
+ * {@link renderAppRoot} writes `main.tf` with one `module "app"` block. Its
+ * `source` is the template's registry address and its `version` is the
+ * requested version, pinned exactly (`version = "1.2.0"`), which is the form
+ * the pin editor (`../pin/edit.ts`) reads and moves, so a rollout finds the
+ * app. The module's outputs are re-exported as `app_<output>`. Day-2 actions
+ * the template declares are addressed through the call, as
+ * `module.app.action.<type>.<name>`, so nothing is written for them here.
+ *
+ * {@link renderAddonCall} writes `addon-<name>.tf` for the app's own root
+ * (ruling C of #4642) with one `module "<name>"` block. An input whose value
+ * is the string `app.<output>` becomes the reference `module.app.<output>`.
+ *
+ * Each input is written as an HCL literal of its engine-neutral kind
+ * (template.yml/v1, `@intentius/chant/template-request`), in the order the
+ * template lists them, with two-space indent and the `=` signs lined up as
+ * `terraform fmt` lines them up. A sensitive input never travels in a
+ * request: the file declares a sensitive root variable of the kind's
+ * Terraform type ({@link terraformInputType}) and passes `var.<name>`, so
+ * the value comes from the root's own secret store.
+ *
+ * The backend, provider and version files are not written here; the caller
+ * writes them in the same pull request. Nothing here reads the disk, so the
+ * output depends on the arguments alone: the same request gives the same
+ * bytes.
+ */
+import { appOutputRef, inputKindProblem, inputRequired } from "@intentius/chant/template-request";
+import { escapeHcl } from "../pin/scan.js";
+import { exactVersion } from "../pin/source.js";
+/** The module block an app root calls its template through. Actions are addressed as `module.app.action...`. */
+export const APP_MODULE_NAME = "app";
+/** The prefix of the root outputs an app root re-exports its module's outputs under. */
+export const APP_OUTPUT_PREFIX = "app_";
+/** The file an app root's module call is written to. */
+export const APP_ROOT_FILE = "main.tf";
+/** The file in the app's root an add-on's module call is written to. */
+export function addonFile(name) {
+    return `addon-${name}.tf`;
+}
+/** Thrown when a request cannot become files. `subject` names the input, output or field at fault. */
+export class TemplateRenderError extends Error {
+    constructor(code, subject, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.subject = subject;
+        this.name = "TemplateRenderError";
+    }
+}
+/**
+ * The Terraform type an input's kind maps to: `string`, `number`, `bool`,
+ * `list(<of>)`, `map(<of>)`, and `any` for an object or for a list or map
+ * whose element kind is not given (`list(any)`, `map(any)`).
+ */
+export function terraformInputType(input) {
+    switch (input.kind) {
+        case "string":
+        case "number":
+        case "bool":
+            return input.kind;
+        case "list":
+        case "map":
+            return `${input.kind}(${input.of ?? "any"})`;
+        case "object":
+            return "any";
+    }
+}
+// ── HCL text ──────────────────────────────────────────────────────────────
+const IDENT = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** An expression that is already HCL: a reference or a type, written as it is. */
+class RawExpr {
+    constructor(raw) {
+        this.raw = raw;
+    }
+}
+const expr = (text) => new RawExpr(text);
+const isScalar = (v) => v === null || typeof v !== "object" || v instanceof RawExpr;
+/** Code-unit order, so the bytes never depend on a locale. */
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function scalar(value) {
+    if (value instanceof RawExpr)
+        return value.raw;
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return `"${escapeHcl(value)}"`;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    throw new Error(`not an HCL scalar: ${typeof value}`);
+}
+/** An object key: bare when it is an identifier, quoted otherwise. */
+const key = (k) => (IDENT.test(k) ? k : `"${escapeHcl(k)}"`);
+/**
+ * A JSON value as an HCL expression at `indent`. A list of scalars sits on
+ * one line; a map, an object and a list holding either open one line per
+ * entry. Map keys are sorted, so the order a request's JSON happened to
+ * carry them in never changes the bytes.
+ */
+function literal(value, indent) {
+    if (isScalar(value))
+        return scalar(value);
+    const inner = `${indent}  `;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.every(isScalar))
+            return `[${value.map(scalar).join(", ")}]`;
+        return `[\n${value.map((v) => `${inner}${literal(v, inner)},\n`).join("")}${indent}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort(byCodeUnit);
+    if (keys.length === 0)
+        return "{}";
+    return `{\n${attributes(keys.map((k) => [key(k), obj[k]]), inner)}${indent}}`;
+}
+/**
+ * Attribute lines at `indent`, with the `=` of each run of one-line
+ * attributes lined up, as `terraform fmt` does. An attribute whose value
+ * spans lines ends the run before it and is lined up with nothing.
+ */
+function attributes(entries, indent) {
+    const rendered = entries.map(([name, value]) => ({ name, text: literal(value, indent) }));
+    let out = "";
+    let run = [];
+    const flush = () => {
+        const width = Math.max(...run.map((r) => r.name.length));
+        for (const r of run)
+            out += `${indent}${r.name.padEnd(width)} = ${r.text}\n`;
+        run = [];
+    };
+    for (const r of rendered) {
+        if (r.text.includes("\n")) {
+            if (run.length > 0)
+                flush();
+            run.push(r);
+            flush();
+        }
+        else
+            run.push(r);
+    }
+    if (run.length > 0)
+        flush();
+    return out;
+}
+function block(header, groups) {
+    const body = groups
+        .filter((g) => g.length > 0)
+        .map((g) => attributes(g, "  "))
+        .join("\n");
+    return `${header} {\n${body}}\n`;
+}
+function checkVersion(request) {
+    const version = exactVersion(request.version);
+    if (!version) {
+        throw new TemplateRenderError("not-a-version", "version", `the request names ${JSON.stringify(request.version)}, and a module call pins an exact version such as "1.2.0"`);
+    }
+    return version;
+}
+function checkSource(source) {
+    if (source.length === 0 || /[\s"]/.test(source)) {
+        throw new TemplateRenderError("bad-name", "source", `the source ${JSON.stringify(source)} is not a registry address`);
+    }
+}
+/** The module arguments for each input the template lists, and a root variable for each sensitive one. */
+function renderInputs(request, inputs, call) {
+    const given = request.inputs ?? {};
+    const known = new Set(inputs.map((i) => i.name));
+    const extra = Object.keys(given)
+        .filter((k) => !known.has(k))
+        .sort(byCodeUnit);
+    if (extra.length > 0) {
+        throw new TemplateRenderError("unknown-input", extra[0], `the template has no input ${extra.map((e) => JSON.stringify(e)).join(", ")}`);
+    }
+    const variables = [];
+    const args = [];
+    for (const input of inputs) {
+        const has = Object.prototype.hasOwnProperty.call(given, input.name);
+        if (input.sensitive) {
+            if (has)
+                throw new TemplateRenderError("sensitive-input", input.name, `${input.name} is sensitive, and a request never carries a secret`);
+            const variable = `${call.varPrefix}${input.name}`;
+            const fields = [
+                ["type", expr(terraformInputType(input))],
+                ["sensitive", true],
+            ];
+            if (input.description)
+                fields.push(["description", input.description]);
+            if (!inputRequired(input))
+                fields.push(["default", "default" in input ? input.default : null]);
+            variables.push(block(`variable "${variable}"`, [fields]));
+            args.push({ name: input.name, value: expr(`var.${variable}`) });
+            continue;
+        }
+        const value = has ? given[input.name] : input.default;
+        if (value === undefined) {
+            if (inputRequired(input))
+                throw new TemplateRenderError("missing-input", input.name, `the request gives no ${input.name}, and the input is required`);
+            continue;
+        }
+        const output = call.appOutputs ? appOutputRef(value) : undefined;
+        if (output !== undefined) {
+            if (!call.appOutputs.has(output)) {
+                throw new TemplateRenderError("unknown-output", output, `${input.name} names app.${output}, and the app module has no output ${output}`);
+            }
+            args.push({ name: input.name, value: expr(`module.${APP_MODULE_NAME}.${output}`) });
+            continue;
+        }
+        const problem = inputKindProblem(input, value);
+        if (problem)
+            throw new TemplateRenderError("input-type", input.name, `${input.name} ${problem}`);
+        args.push({ name: input.name, value });
+    }
+    return { variables, args };
+}
+function moduleBlock(name, source, version, args) {
+    return block(`module "${name}"`, [
+        [
+            ["source", source],
+            ["version", version],
+        ],
+        args.map((a) => [a.name, a.value]),
+    ]);
+}
+function header(request, what) {
+    const template = request.template.replace(/[\r\n]/g, " ");
+    return `# ${what}, from the template ${template}. Written by chant from a template request; a rollout moves the version.\n`;
+}
+/**
+ * The root of a new app: `main.tf` with one `module "app"` block calling
+ * the template at the requested version, and an `app_<output>` root output
+ * for each of the module's outputs. Throws {@link TemplateRenderError}.
+ */
+export function renderAppRoot(options) {
+    const { request, source, inputs, outputs = [] } = options;
+    if (request.kind !== "app")
+        throw new TemplateRenderError("wrong-kind", "kind", `the request is for an ${request.kind}, and an app root renders an app`);
+    checkSource(source);
+    const version = checkVersion(request);
+    const { variables, args } = renderInputs(request, inputs, { name: APP_MODULE_NAME, varPrefix: `${APP_MODULE_NAME}_` });
+    const parts = [header(request, `The app ${request.app}`), ...variables, moduleBlock(APP_MODULE_NAME, source, version, args)];
+    for (const o of outputs) {
+        if (!IDENT.test(o.name))
+            throw new TemplateRenderError("bad-name", o.name, `the module output ${JSON.stringify(o.name)} is not a Terraform name`);
+        const fields = [["value", expr(`module.${APP_MODULE_NAME}.${o.name}`)]];
+        if (o.description)
+            fields.push(["description", o.description]);
+        if (o.sensitive)
+            fields.push(["sensitive", true]);
+        parts.push(block(`output "${APP_OUTPUT_PREFIX}${o.name}"`, [fields]));
+    }
+    return [{ path: APP_ROOT_FILE, text: parts.join("\n") }];
+}
+/**
+ * An add-on's module call for the app's root: `addon-<name>.tf` with one
+ * `module "<name>"` block. A value `app.<output>` becomes
+ * `module.app.<output>`, refused with `unknown-output` when the app module
+ * has no such output. Throws {@link TemplateRenderError}.
+ */
+export function renderAddonCall(options) {
+    const { request, source, inputs, appOutputs } = options;
+    if (request.kind !== "addon")
+        throw new TemplateRenderError("wrong-kind", "kind", `the request is for an ${request.kind}, and an add-on call renders an addon`);
+    const name = request.addon;
+    if (!name || !IDENT.test(name))
+        throw new TemplateRenderError("bad-name", "addon", `an add-on request names its add-on, as a Terraform name; it gave ${JSON.stringify(name ?? null)}`);
+    if (name === APP_MODULE_NAME)
+        throw new TemplateRenderError("bad-name", "addon", `an add-on cannot be named ${APP_MODULE_NAME}: the app's own module call has that name`);
+    checkSource(source);
+    const version = checkVersion(request);
+    const outputs = new Set(appOutputs.map((o) => (typeof o === "string" ? o : o.name)));
+    const { variables, args } = renderInputs(request, inputs, { name, varPrefix: `${name}_`, appOutputs: outputs });
+    const parts = [header(request, `The add-on ${name} of the app ${request.app}`), ...variables, moduleBlock(name, source, version, args)];
+    return { path: addonFile(name), text: parts.join("\n") };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-terraform",
-  "version": "0.124.56",
+  "version": "0.124.58",
   "type": "module",
   "files": [
     "src/",
@@ -34,6 +34,11 @@
       "types": "./dist/pin/index.d.ts",
       "default": "./dist/pin/index.js"
     },
+    "./template": {
+      "development": "./src/template/index.ts",
+      "types": "./dist/template/index.d.ts",
+      "default": "./dist/template/index.js"
+    },
     "./module-catalog": {
       "development": "./src/module-catalog/index.ts",
       "types": "./dist/module-catalog/index.d.ts",
@@ -88,7 +93,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.56",
+    "@intentius/chant": "^0.124.58",
     "zod": "^4.3.6"
   },
   "description": "terraform lexicon for chant, existing Terraform root modules as declarable entities",