@intentius/chant 0.102.0 → 0.104.0

package/src/pr-loop.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The pull-request loop's report and note (#3183): the schema, the note a
+ * reviewer reads at each stage, and the status line.
+ *
+ * The report is what the terragucci plan report (#3349) reads, so the JSON
+ * has a golden, and so does the note rendered from it.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { composeChangeSet, type ChangeSetPart } from "./change-set";
+import {
+  describePlanChanged,
+  memberCounts,
+  PR_REPORT_SCHEMA_ID,
+  prApproveCommand,
+  prNoteMarker,
+  prOp,
+  prStatusDescription,
+  prStatusState,
+  renderPrNote,
+  type PrReport,
+} from "./pr-loop";
+import { contract, validSchema } from "./workspace/__fixtures__/contract-repo";
+import schema from "./workspace/pr-report.schema.json";
+import changeSetSchema from "./workspace/change-set.schema.json";
+
+const { expectValid } = contract(schema);
+const { expectValid: expectValidChangeSet } = contract(changeSetSchema);
+
+const DIR = join(import.meta.dirname, "__fixtures__", "pr-loop");
+
+function golden(name: string, text: string): void {
+  const path = join(DIR, name);
+  if (process.env.UPDATE_GOLDEN) writeFileSync(path, text);
+  expect(text).toBe(readFileSync(path, "utf-8"));
+}
+
+const hex = (n: number) => n.toString(16).padStart(64, "0");
+
+function part(member: string, n: number, entries: Array<{ address: string; action: "create" | "update" | "delete" | "replace" }>): ChangeSetPart {
+  return {
+    member: { member, lexicon: "terraform", planner: "tofu", status: "planned", planDigest: `jcs1-sha256:${hex(n)}`, holes: [] },
+    entries: entries.map((e) => ({
+      member,
+      lexicon: "terraform",
+      planner: "tofu",
+      address: e.address,
+      type: e.address.split(".")[0],
+      action: e.action,
+      attributes: e.action === "update" ? [{ path: "input", before: "v1", after: "v2" }] : [],
+    })),
+  };
+}
+
+const doc = composeChangeSet([
+  part("a", 1, [{ address: "terraform_data.subnet", action: "update" }]),
+  part("app", 2, []),
+]);
+
+const planReport: PrReport = {
+  $schema: PR_REPORT_SCHEMA_ID,
+  contract: 1,
+  stage: "plan",
+  pr: 12,
+  env: "prod",
+  base: "1".repeat(40),
+  head: "2".repeat(40),
+  op: prOp(12),
+  gate: "pr-apply",
+  digest: doc.digest,
+  status: "planned",
+  approval: { status: "pending" },
+  selection: { changed: ["a"], dependents: ["app"], unclaimed: [], indeterminate: [], waves: [["a"], ["app"]] },
+  members: [
+    { member: "a", component: "a", planDigest: `jcs1-sha256:${hex(1)}`, status: "planned", counts: memberCounts(doc, "a") },
+    { member: "app", component: "app", planDigest: `jcs1-sha256:${hex(2)}`, status: "planned", counts: memberCounts(doc, "app") },
+  ],
+  changeSet: doc,
+};
+
+const changedDigest = `jcs1-sha256:${hex(99)}`;
+const refusedReport: PrReport = {
+  ...planReport,
+  stage: "apply",
+  status: "refused",
+  refusal: "plan-changed",
+  approval: { status: "changed", approved: changedDigest },
+  message: describePlanChanged({ op: planReport.op, gate: planReport.gate, digest: planReport.digest, approval: { status: "changed", approved: changedDigest } }),
+};
+
+const appliedReport: PrReport = {
+  ...planReport,
+  stage: "apply",
+  status: "applied",
+  approval: { status: "approved", approvedBy: ["github:alice"] },
+  members: [
+    { ...planReport.members[0], status: "applied" },
+    { ...planReport.members[1], status: "applied", inputsMoved: ["a"] },
+  ],
+};
+
+describe("the pr-report schema", () => {
+  test("is a valid schema and names this module's id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(PR_REPORT_SCHEMA_ID);
+  });
+
+  test("every stage's report validates, and its change set validates against the change-set schema", () => {
+    for (const report of [planReport, refusedReport, appliedReport]) {
+      expectValid(report);
+      expectValidChangeSet(report.changeSet);
+      expect(report.changeSet.digest).toBe(report.digest);
+    }
+  });
+
+  test("the report has a golden", () => {
+    golden("pr-plan.golden.json", JSON.stringify(planReport, null, 2) + "\n");
+  });
+});
+
+describe("the note", () => {
+  test("the plan stage names every member, the digest and the approve command, then the grouped summary", () => {
+    const note = renderPrNote(planReport, { approver: "github:<your-login>" });
+    expect(note.startsWith(prNoteMarker("prod"))).toBe(true);
+    expect(note).toContain(`chant approve pr-12 pr-apply --plan ${doc.digest} --approver github:<your-login> --sign`);
+    expect(note).toContain("### Plan summary");
+    golden("pr-plan.note.golden.md", note);
+  });
+
+  test("a refused apply names both digests and says nothing applied", () => {
+    const note = renderPrNote(refusedReport);
+    expect(note).toContain("The apply refused.");
+    expect(note).toContain("nothing was applied");
+    expect(note).toContain(`approved: ${changedDigest}; planned now: ${doc.digest}`);
+    golden("pr-apply-refused.note.golden.md", note);
+  });
+
+  test("an applied member whose inputs moved says so", () => {
+    const note = renderPrNote(appliedReport);
+    expect(note).toContain("applied, inputs from a moved");
+    expect(note).toContain("Approved by `github:alice` for this digest.");
+    golden("pr-apply-applied.note.golden.md", note);
+  });
+
+  test("a small limit leaves the summary out rather than cutting the table", () => {
+    const note = renderPrNote(planReport, { limit: 800 });
+    expect(note).toContain("| `app` |");
+    expect(note).not.toContain("### Plan summary");
+  });
+});
+
+describe("the status", () => {
+  test("describes each stage in at most 140 characters", () => {
+    expect(prStatusDescription(planReport)).toMatch(/^2 members: 1 to change, 0 to destroy or replace; plan [0-9a-f]{12}$/);
+    expect(prStatusDescription(refusedReport)).toBe("refused: the plan changed after review");
+    expect(prStatusDescription(appliedReport)).toMatch(/^applied 2 members/);
+    for (const r of [planReport, refusedReport, appliedReport]) expect(prStatusDescription(r).length).toBeLessThanOrEqual(140);
+  });
+
+  test("an unapproved apply is pending, a moved plan fails, an applied one succeeds", () => {
+    expect(prStatusState({ ...refusedReport, refusal: "not-approved" })).toBe("pending");
+    expect(prStatusState(refusedReport)).toBe("failure");
+    expect(prStatusState(appliedReport)).toBe("success");
+  });
+
+  test("the approve command binds the digest and asks for a signature", () => {
+    expect(prApproveCommand(planReport, "gitlab:ana")).toBe(`chant approve pr-12 pr-apply --plan ${doc.digest} --approver gitlab:ana --sign`);
+  });
+});

package/src/pr-loop.ts

@@ -0,0 +1,324 @@
+/**
+ * The pull-request loop (#3183): plan the members a change reaches, show the
+ * plan on the pull request, and apply it on merge only when the plan is the
+ * one a reviewer approved.
+ *
+ * `chant components pr-plan` and `chant components pr-apply` run it, and the
+ * generated CI for GitHub, GitLab and Forgejo calls them
+ * (`components/pr-pipeline.ts`). This module holds the parts that need no
+ * runner: the gate's names, the report both commands write, the pull-request
+ * note rendered from it and the status line. terragucci reads the report and
+ * renders the note from one bundled file with no TypeScript toolchain
+ * (#3421), so this imports `./change-set` and `./plan-summary` and nothing
+ * else; `pr-loop-bundle.test.ts` holds that.
+ *
+ * ## What the gate binds
+ *
+ * One gate per pull request: op `pr-<number>`, gate `pr-apply` unless the
+ * pipeline names another. It binds the digest of the change-set document over
+ * every planned member (`changeSetDigest`, #3181), the same digest a gated
+ * wave binds over its members (#3049). A reviewer approves it with `chant
+ * approve pr-<number> pr-apply --plan <digest>`. The op carries the number so
+ * that one pull request's approval never answers another's, and the gate name
+ * stays fixed so a workspace can require signed approvals for it under
+ * `identity.gates` (#3163).
+ *
+ * On merge the apply plans the same members again, before anything applies,
+ * and decides the gate against the new digest. The same plan applies; a moved
+ * plan stops with both digests named and nothing applied.
+ */
+
+import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
+import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
+
+/** The schema a pull-request report names in `$schema`. */
+export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json";
+
+/** The read-contract version the report follows. */
+export const PR_REPORT_CONTRACT = 1;
+
+/** The gate a pull request's apply waits on, unless the pipeline names another. */
+export const PR_APPLY_GATE = "pr-apply";
+
+/** The op a pull request's gate is recorded under: `pr-<number>`. */
+export function prOp(pr: number): string {
+  return `pr-${pr}`;
+}
+
+/** The hidden line that marks the pull request's note, one per environment. */
+export function prNoteMarker(env: string): string {
+  return `<!-- chant-pr:${env} -->`;
+}
+
+/** The status contexts the two stages set on the commit. */
+export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply" } as const;
+
+/** Changes a member's plan proposes, by the actions a reviewer reads. */
+export interface PrMemberCounts {
+  create: number;
+  update: number;
+  replace: number;
+  delete: number;
+}
+
+/** Where one member got to. */
+export type PrMemberStatus =
+  /** Planned, nothing applied (the plan stage, or an apply that stopped). */
+  | "planned"
+  /** The plan failed. */
+  | "plan-failed"
+  /** Applied the approved plan. */
+  | "applied"
+  /** The apply failed. */
+  | "failed"
+  /** Not applied because a member it depends on failed. */
+  | "blocked";
+
+export interface PrMember {
+  /** The member's name in the change set: a root, for a terraform-family step. */
+  member: string;
+  /** The component whose step planned it. */
+  component: string;
+  /** What a gate on this member alone binds. `null` when it failed to plan. */
+  planDigest: string | null;
+  status: PrMemberStatus;
+  counts: PrMemberCounts;
+  error?: string;
+  /**
+   * Components this one depends on whose outputs changed when they applied
+   * (apply stage). Its applied plan read the values from before, so the next
+   * run plans it again.
+   */
+  inputsMoved?: string[];
+}
+
+/** Where the approval stands for the planned digest. */
+export interface PrApproval {
+  /**
+   * `approved`: an approval stands for this digest. `changed`: one stands for
+   * another digest, so the plan moved since someone approved it. `pending`:
+   * none stands.
+   */
+  status: "approved" | "changed" | "pending";
+  /** Who approved this digest. */
+  approvedBy?: string[];
+  /** With `changed`: the digest that was approved. */
+  approved?: string;
+}
+
+/** How a stage ended. */
+export type PrStatus =
+  /** Plan stage: every member planned. */
+  | "planned"
+  /** Plan stage: a member failed to plan. Apply stage: the same, so nothing applied. */
+  | "plan-failed"
+  /** Nothing the change touches is deployed by a component. */
+  | "nothing"
+  /** Apply stage: every member applied. */
+  | "applied"
+  /** Apply stage: a member failed to apply. Its dependents did not run. */
+  | "failed"
+  /** Apply stage: nothing applied, see `refusal`. */
+  | "refused";
+
+/** Why an apply refused. */
+export type PrRefusal =
+  /** No approval stands for any plan of this pull request. */
+  | "not-approved"
+  /** The approval stands for another digest: the plan changed after review. */
+  | "plan-changed"
+  /** The approval names someone who has not approved the pull request on the forge. */
+  | "not-a-reviewer"
+  /** No pull request merged this commit, so there is no approval to read. */
+  | "no-pull-request";
+
+/**
+ * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
+ * The terragucci plan report (#3349) reads it; fields are only ever added.
+ */
+export interface PrReport {
+  $schema: typeof PR_REPORT_SCHEMA_ID;
+  contract: typeof PR_REPORT_CONTRACT;
+  stage: "plan" | "apply";
+  /** The pull or merge request number, when known. */
+  pr: number | null;
+  env: string;
+  /** The commit the change is measured from: the merge base of the given base and `head`. */
+  base: string;
+  head: string;
+  /** The gate's ledger entry: `_gates/<op>.jsonl` on `chant/lifecycle`. */
+  op: string;
+  gate: string;
+  /** The change-set digest of what this stage planned. What the gate binds. */
+  digest: string;
+  status: PrStatus;
+  refusal?: PrRefusal;
+  /** The refusal or failure, as printed. */
+  message?: string;
+  approval: PrApproval;
+  /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
+  selection: {
+    changed: string[];
+    dependents: string[];
+    unclaimed: string[];
+    indeterminate: string[];
+    /** The components in dependency order, a wave per entry. */
+    waves: string[][];
+  };
+  members: PrMember[];
+  changeSet: ChangeSetDocument;
+}
+
+/** The counts a member's entries add up to. */
+export function memberCounts(doc: Pick<ChangeSetDocument, "summary">, member: string): PrMemberCounts {
+  const by = doc.summary.byMember[member] ?? {};
+  const n = (a: ChangeSetAction) => by[a] ?? 0;
+  return { create: n("create"), update: n("update"), replace: n("replace"), delete: n("delete") };
+}
+
+/** The approve command a reviewer runs for this report's digest. */
+export function prApproveCommand(report: Pick<PrReport, "op" | "gate" | "digest">, approver = "<you>"): string {
+  return `chant approve ${report.op} ${report.gate} --plan ${report.digest} --approver ${approver} --sign`;
+}
+
+/**
+ * The refusal when the approved digest is not the planned one: both digests,
+ * that nothing applied, and how to close it.
+ */
+export function describePlanChanged(report: Pick<PrReport, "op" | "gate" | "digest" | "approval">): string {
+  return (
+    `The plan changed after review, so nothing was applied. ` +
+    `approved: ${report.approval.approved ?? "(none)"}; planned now: ${report.digest}. ` +
+    `Read the new plan, and if it is right, approve it: ${prApproveCommand(report)}; then run the apply again.`
+  );
+}
+
+const short = (sha: string): string => sha.slice(0, 12);
+const code = (s: string): string => "`" + s.replaceAll("`", "'") + "`";
+
+const STATUS_WORDS: Record<PrMemberStatus, string> = {
+  planned: "planned",
+  "plan-failed": "plan failed",
+  applied: "applied",
+  failed: "apply failed",
+  blocked: "blocked",
+};
+
+function headline(report: PrReport): string {
+  const n = report.members.length;
+  const members = `${n} member${n === 1 ? "" : "s"}`;
+  switch (report.status) {
+    case "nothing":
+      return "Nothing to plan: no component deploys what this change touches.";
+    case "planned":
+      return `Planned ${members}.`;
+    case "plan-failed":
+      return `Planning failed for ${report.members.filter((m) => m.status === "plan-failed").length} of ${members}, so nothing can apply.`;
+    case "applied":
+      return `Applied ${members}.`;
+    case "failed":
+      return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
+    case "refused":
+      return "The apply refused.";
+  }
+}
+
+function approvalLines(report: PrReport, approver: string): string[] {
+  const a = report.approval;
+  if (report.status === "nothing") return [];
+  if (a.status === "approved") return [`Approved by ${(a.approvedBy ?? []).map(code).join(", ")} for this digest.`];
+  const lines =
+    a.status === "changed"
+      ? [`An approval stands for ${code(a.approved ?? "(none)")}, not for this digest: the plan changed since it was approved.`]
+      : ["Not approved yet."];
+  if (report.stage === "plan" && report.status === "planned") {
+    lines.push(
+      "",
+      "A reviewer who approved this pull request approves the plan with:",
+      "",
+      "```",
+      prApproveCommand(report, approver),
+      "```",
+      "",
+      "It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.",
+    );
+  }
+  return lines;
+}
+
+/**
+ * The pull-request note: the stage's headline, a row per member, the digest
+ * and the approval, then the grouped plan summary (#3188) in whatever room
+ * `limit` leaves. The note starts with {@link prNoteMarker}, so the same
+ * comment is updated by every push and by the apply.
+ */
+export function renderPrNote(report: PrReport, options: { limit?: number; approver?: string } = {}): string {
+  const limit = options.limit ?? GITHUB_COMMENT_LIMIT;
+  const out: string[] = [
+    prNoteMarker(report.env),
+    `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}`,
+    "",
+    `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
+  ];
+  if (report.message) out.push("", `> ${report.message.split("\n").join("\n> ")}`);
+  if (report.members.length > 0) {
+    out.push("", "| Member | Component | Status | Create | Update | Replace | Delete |", "|---|---|---|---:|---:|---:|---:|");
+    for (const m of report.members) {
+      const status = STATUS_WORDS[m.status] + (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "");
+      out.push(`| ${code(m.member)} | ${m.component} | ${status} | ${m.counts.create} | ${m.counts.update} | ${m.counts.replace} | ${m.counts.delete} |`);
+    }
+    if (report.members.some((m) => m.inputsMoved?.length)) {
+      out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
+    }
+  }
+  if (report.selection.unclaimed.length > 0) {
+    out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
+  }
+  if (report.status !== "nothing") {
+    out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
+  }
+  const head = out.join("\n") + "\n";
+  if (report.status === "nothing" || report.changeSet.members.length === 0) return head;
+  const room = limit - [...head].length - 1;
+  if (room < 400) return head;
+  return head + "\n" + renderPlanSummaryMarkdown(groupChangeSet(report.changeSet), { limit: room, command: "chant change-set summary .chant/pr/change-set.json" });
+}
+
+/** A commit status's description, at most 140 characters (GitHub's limit). */
+export function prStatusDescription(report: PrReport): string {
+  const n = report.members.length;
+  const sum = report.members.reduce(
+    (acc, m) => ({ change: acc.change + m.counts.create + m.counts.update + m.counts.replace, destroy: acc.destroy + m.counts.delete + m.counts.replace }),
+    { change: 0, destroy: 0 },
+  );
+  const digest = report.digest ? `; plan ${report.digest.replace(/^(?:jcs1-)?sha256:/, "").slice(0, 12)}` : "";
+  let text: string;
+  switch (report.status) {
+    case "nothing":
+      text = "nothing to plan";
+      break;
+    case "planned":
+      text = `${n} member${n === 1 ? "" : "s"}: ${sum.change} to change, ${sum.destroy} to destroy or replace${digest}`;
+      break;
+    case "plan-failed":
+      text = `a member failed to plan${digest}`;
+      break;
+    case "applied":
+      text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
+      break;
+    case "failed":
+      text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
+      break;
+    case "refused":
+      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+      break;
+  }
+  return text.length > 140 ? text.slice(0, 137) + "..." : text;
+}
+
+/** The commit status state for a report: success, failure, or pending while it waits on approval. */
+export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
+  if (report.status === "planned" || report.status === "applied" || report.status === "nothing") return "success";
+  if (report.status === "refused" && report.refusal === "not-approved") return "pending";
+  return "failure";
+}

package/src/telemetry-attribution.test.ts

@@ -2,7 +2,15 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { mergeResourceAttributes, resolveTelemetryAttribution, TELEMETRY_ATTRIBUTES, telemetryEnvironment } from "./telemetry-attribution";
+import {
+  mergeResourceAttributes,
+  RELEASE_ATTRIBUTES_VARIABLE,
+  releaseAttributesSuffix,
+  releaseEnvironment,
+  resolveTelemetryAttribution,
+  TELEMETRY_ATTRIBUTES,
+  telemetryEnvironment,
+} from "./telemetry-attribution";
 
 const scratch = mkdtempSync(join(tmpdir(), "chant-2558-"));
 afterAll(() => rmSync(scratch, { recursive: true, force: true }));
@@ -89,3 +97,17 @@ describe("mergeResourceAttributes", () => {
     expect(mergeResourceAttributes("", "a=1")).toBe("a=1");
   });
 });
+
+describe("release attributes (#3061, ws-081)", () => {
+  test("the suffix starts with a comma, percent-encodes, and is empty when the release knows nothing", () => {
+    expect(releaseAttributesSuffix({ version: "sha256:abc", revision: "0123abc" })).toBe(",service.version=sha256%3Aabc,vcs.ref.head.revision=0123abc");
+    expect(releaseAttributesSuffix({ revision: "0123abc" })).toBe(",vcs.ref.head.revision=0123abc");
+    expect(releaseAttributesSuffix({})).toBe("");
+    expect(releaseAttributesSuffix(undefined)).toBe("");
+  });
+
+  test("the environment carries the suffix under CHANT_RELEASE_ATTRIBUTES, or nothing", () => {
+    expect(releaseEnvironment({ revision: "r" })).toEqual({ [RELEASE_ATTRIBUTES_VARIABLE]: ",vcs.ref.head.revision=r" });
+    expect(releaseEnvironment({})).toEqual({});
+  });
+});

package/src/telemetry-attribution.ts

@@ -143,3 +143,54 @@ export function mergeResourceAttributes(existing: string, extra: string): string
   const added = extra.split(",").filter((kv) => kv !== "" && !have.has(kv.split("=")[0]!));
   return [existing, ...added].filter((s) => s !== "").join(",");
 }
+
+// ── Release attributes (#3061, ws-081) ─────────────────────────────
+
+/**
+ * The environment variable a deploy sets to the release attributes, as a
+ * suffix for `OTEL_RESOURCE_ATTRIBUTES`. A stamped workload's generated
+ * output appends it where the platform expands variables (Compose
+ * interpolation, a Kubernetes `$(VAR)` reference), so the committed files are
+ * the same bytes whatever is released.
+ */
+export const RELEASE_ATTRIBUTES_VARIABLE = "CHANT_RELEASE_ATTRIBUTES";
+
+/**
+ * The pod-template annotation a Kubernetes release writes the suffix to. A
+ * stamped container reads it into {@link RELEASE_ATTRIBUTES_VARIABLE} through
+ * the downward API; an absent annotation reads as empty.
+ */
+export const RELEASE_ATTRIBUTES_ANNOTATION = "chant.intentius.io/release-attributes";
+
+/** What the step that deploys a release knows: the artifact it promoted and the commit it came from. */
+export interface ReleaseIdentity {
+  /** `service.version`: the digest of the artifact the run promoted, the release record's `digest`. */
+  version?: string;
+  /** `vcs.ref.head.revision`: the commit, the release record's `gitSha`. */
+  revision?: string;
+}
+
+/**
+ * The release attributes as a suffix for `OTEL_RESOURCE_ATTRIBUTES`: each
+ * pair preceded by a comma and percent-encoded the way
+ * {@link telemetryEnvironment} encodes, or `""` when the release knows
+ * neither. The build-time list always has `chant.decl`, so the suffix never
+ * starts the list.
+ */
+export function releaseAttributesSuffix(release: ReleaseIdentity | undefined): string {
+  if (!release) return "";
+  const pairs: [string, string | undefined][] = [
+    ["service.version", release.version],
+    ["vcs.ref.head.revision", release.revision],
+  ];
+  return pairs
+    .filter((p): p is [string, string] => p[1] !== undefined && p[1] !== "")
+    .map(([k, v]) => `,${k}=${encodeURIComponent(v)}`)
+    .join("");
+}
+
+/** The variables a deploy step exports for a release: {@link RELEASE_ATTRIBUTES_VARIABLE}, or nothing. */
+export function releaseEnvironment(release: ReleaseIdentity | undefined): Record<string, string> {
+  const suffix = releaseAttributesSuffix(release);
+  return suffix === "" ? {} : { [RELEASE_ATTRIBUTES_VARIABLE]: suffix };
+}

package/src/terraform/hcl2json.test.ts

@@ -0,0 +1,21 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+describe("hcl2json loader", () => {
+  // A bundle that only reads HCL must not load the graph, the state reader or
+  // the carve tables behind them.
+  test("imports nothing from the graph, state or carve modules", () => {
+    const src = readFileSync(join(__dirname, "hcl2json.ts"), "utf-8");
+    const local = [...src.matchAll(/from "(\.\/[^"]+)"/g)].map((m) => m[1]);
+    expect(local.every((p) => p === "./types")).toBe(true);
+  });
+
+  test("parse.ts still re-exports the loader API", async () => {
+    const parse = await import("./parse");
+    const loader = await import("./hcl2json");
+    expect(parse.loadHcl2json).toBe(loader.loadHcl2json);
+    expect(parse.Hcl2JsonNotInstalled).toBe(loader.Hcl2JsonNotInstalled);
+    expect(parse.HCL2JSON_RECORD_ENV).toBe(loader.HCL2JSON_RECORD_ENV);
+  });
+});