@intentius/chant 0.124.31 → 0.124.33

package/src/components/release-compile.ts

@@ -15,7 +15,14 @@
  * ./promote.ts: a literal path in a deploy step's `template`, `manifest` or
  * `values` field ({@link TEMPLATE_FIELDS}), read after the environment's build
  * command has run. A path with the `archive:` prefix names the file after it.
- * A path that names a directory, such as a chart, is not a template.
+ *
+ * Since #4155 a cut also records the other local paths a deploy step names
+ * ({@link recordedInputRefs}: a Helm chart, a kustomize directory, a sync's
+ * source tree, the fields `./deploy-inputs.ts` lists). A directory is
+ * recorded file by file and named in the target's `trees`; a file that is not
+ * UTF-8 is recorded as base64. Such a path that does not exist after the
+ * build, as a chart named from a repository, is not recorded, and the
+ * promote leaves it as written.
  *
  * A project with no components (#4046) is compiled the way `chant build --env
  * <env> -o <output>` builds it ({@link compileBuildOutput}): every file that
@@ -25,6 +32,7 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
+import { isUtf8 } from "node:buffer";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { loadChantConfig, type ChantConfig } from "../config";
@@ -40,7 +48,8 @@ import { memoryGateLedgerPort } from "../op/gate";
 import type { ReleaseArtifact, ReleaseParam } from "../lifecycle/release-store";
 
 /** The deploy step fields whose literal file paths are a component's templates. */
-export const TEMPLATE_FIELDS: readonly string[] = ["template", "manifest", "values"];
+export { TEMPLATE_FIELDS } from "./deploy-inputs";
+import { DEPLOY_INPUT_FIELDS, directoryFiles, ignoredByGit, TEMPLATE_FIELDS, walkFiles } from "./deploy-inputs";
 
 /** The prefix a step may write before an archive-relative template path. */
 const ARCHIVE_PREFIX = "archive:";
@@ -61,7 +70,9 @@ export interface TemplateRef {
 export interface CompiledTemplate {
   component: string | null;
   path: string;
+  /** The text, or the base64 of the bytes under `encoding: "base64"`. */
   content: string;
+  encoding?: "base64";
 }
 
 /** What one environment compiles to. */
@@ -84,6 +95,8 @@ export interface CompiledTarget {
   /** For each component, the file that declares it, relative to the member's directory. */
   componentFiles: Record<string, string>;
   templates: CompiledTemplate[];
+  /** The directories recorded file by file in `templates` (#4155). Absent from a compiler written before #4155. */
+  trees?: Array<{ component: string | null; path: string }>;
 }
 
 /** Compiles a member for one environment, and builds its artifacts. The cut talks to a compiler only, so a test can hand it fixtures. */
@@ -134,6 +147,40 @@ export function templateRefs(component: DriverComponent): TemplateRef[] {
   return out;
 }
 
+/** A path a deploy step names that a cut records (#4155): a {@link TemplateRef}, and whether its field is a template field, which must exist. */
+export interface RecordedInputRef extends TemplateRef {
+  /** True for `template`, `manifest` and `values`, whose path must exist after the build. */
+  required: boolean;
+}
+
+/** Every literal path a component's deploy names that a cut records: {@link templateRefs}, plus each kind's own fields in `DEPLOY_INPUT_FIELDS`. */
+export function recordedInputRefs(component: DriverComponent): RecordedInputRef[] {
+  const out: RecordedInputRef[] = [];
+  for (const { phase, step } of stepsOf(component.deploy)) {
+    if (BUILD_STEP_KINDS.includes(step.kind) || PUBLISH_STEP_KINDS.includes(step.kind)) continue;
+    for (const field of recordedFields(step.kind)) {
+      const raw = step[field];
+      for (const value of Array.isArray(raw) ? raw : [raw]) {
+        if (!isLiteralPath(value)) continue;
+        const path = value.startsWith(ARCHIVE_PREFIX) ? value.slice(ARCHIVE_PREFIX.length) : value;
+        out.push({ component: component.name, phase, kind: step.kind, field, value, path, required: TEMPLATE_FIELDS.includes(field) });
+      }
+    }
+  }
+  return out;
+}
+
+/** The fields of a step of `kind` whose paths a cut records and a promote points at the recorded copy. */
+export function recordedFields(kind: string): string[] {
+  return [...TEMPLATE_FIELDS, ...(DEPLOY_INPUT_FIELDS[kind] ?? [])];
+}
+
+/** A file's bytes as a template: its text when it is UTF-8, else base64. */
+export function templateOf(component: string | null, path: string, file: string): CompiledTemplate {
+  const bytes = readFileSync(file);
+  return isUtf8(bytes) ? { component, path, content: bytes.toString("utf-8") } : { component, path, content: bytes.toString("base64"), encoding: "base64" };
+}
+
 /** A component's build-time steps ({@link BUILD_STEP_KINDS}), each as declared, in composition order. */
 export function buildStepsOf(component: DriverComponent): DriverStep[] {
   return stepsOf(component.deploy).map((s) => s.step).filter((s) => BUILD_STEP_KINDS.includes(s.kind));
@@ -191,8 +238,19 @@ export interface CompileInputs {
   output?: string;
   /** For a project with no components: build only this lexicon, as `chant build --lexicon` does. */
   lexicon?: string;
+  /**
+   * The release's label (#4168, decision 5), passed to every compile and
+   * artifact build as `CHANT_RELEASE_LABEL`, so a version reaches the build
+   * without a version-bump commit. A build parameter reads it by declaring
+   * `env: "CHANT_RELEASE_LABEL"`, and a build step's own tool (cargo, npm)
+   * reads the variable. Unset for a cut with no label.
+   */
+  releaseLabel?: string;
 }
 
+/** The variable a cut's label reaches the build through (#4168). */
+export const RELEASE_LABEL_ENV = "CHANT_RELEASE_LABEL";
+
 /**
  * Where a project with no components writes its build output when the cut
  * names no `-o`. YAML, since the k8s and helm serializers write YAML whatever
@@ -258,21 +316,33 @@ export async function compileEnvironment(inputs: CompileInputs, env: string): Pr
   if (declared === 0) return compileBuildOutput(inputs, env, config);
   const rel = (p: string): string => (isAbsolute(p) ? relative(inputs.projectDir, p) : p);
   const templates: CompiledTemplate[] = [];
+  const trees: Array<{ component: string; path: string }> = [];
   const seen = new Set<string>();
   for (const { component } of components) {
-    for (const ref of templateRefs(component)) {
+    for (const ref of recordedInputRefs(component)) {
       const key = `${ref.component}\u0000${ref.path}`;
       if (seen.has(key)) continue;
       seen.add(key);
       const file = resolve(inputs.projectDir, ref.path);
       if (!existsSync(file)) {
+        if (!ref.required) continue;
         throw new ReleaseCompileError(
           `component "${ref.component}": its ${ref.kind} step in phase "${ref.phase}" reads ${ref.field} "${ref.value}", ` +
             `and no such file exists after the build for "${env}"`,
         );
       }
-      if (!statSync(file).isFile()) continue;
-      templates.push({ component: ref.component, path: ref.path, content: readFileSync(file, "utf-8") });
+      if (statSync(file).isFile()) {
+        templates.push(templateOf(ref.component, ref.path, file));
+        continue;
+      }
+      // #4155: a directory, file by file. One git ignores is the build's output, recorded whole.
+      const files = ignoredByGit(inputs.projectDir, ref.path) ? walkFiles(inputs.projectDir, ref.path) : directoryFiles(inputs.projectDir, ref.path);
+      const dir = ref.path.replace(/\/+$/, "");
+      for (const f of files) {
+        const under = relative(resolve(inputs.projectDir, dir), resolve(inputs.projectDir, f)).split("\\").join("/");
+        templates.push(templateOf(ref.component, `${dir}/${under}`, resolve(inputs.projectDir, f)));
+      }
+      trees.push({ component: ref.component, path: dir });
     }
   }
   return {
@@ -284,6 +354,7 @@ export async function compileEnvironment(inputs: CompileInputs, env: string): Pr
     buildInputs: Object.fromEntries(components.map(({ component }) => [component.name, buildInputPaths(component)])),
     componentFiles: Object.fromEntries(components.map(({ component, file }) => [component.name, rel(file)])),
     templates,
+    trees,
   };
 }
 
@@ -408,10 +479,20 @@ export function ownChantCommand(): string[] {
   return [process.execPath, ...process.execArgv, main];
 }
 
-function runChild(command: readonly string[], args: readonly string[], cwd: string, env: string): Promise<{ code: number; stdout: string; stderr: string }> {
+function runChild(
+  command: readonly string[],
+  args: readonly string[],
+  cwd: string,
+  env: string,
+  releaseLabel?: string,
+): Promise<{ code: number; stdout: string; stderr: string }> {
   return new Promise((resolvePromise, reject) => {
     const [bin, ...lead] = command;
-    const child = spawn(bin, [...lead, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, CHANT_ENV: env } });
+    const childEnv: NodeJS.ProcessEnv = { ...process.env, CHANT_ENV: env };
+    // A label never leaks in from the caller's shell: only the cut sets it.
+    delete childEnv[RELEASE_LABEL_ENV];
+    if (releaseLabel !== undefined) childEnv[RELEASE_LABEL_ENV] = releaseLabel;
+    const child = spawn(bin, [...lead, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: childEnv });
     const out: Buffer[] = [];
     const err: Buffer[] = [];
     child.stdout.on("data", (c: Buffer) => out.push(c));
@@ -440,7 +521,7 @@ export function spawnTargetCompiler(inputs: CompileInputs, command: readonly str
     return args;
   };
   const call = async (env: string, extra: string[]): Promise<unknown> => {
-    const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env);
+    const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env, inputs.releaseLabel);
     if (run.code !== 0) throw new ReleaseCompileError(`compiling "${env}" failed (exit ${run.code})`);
     try {
       return JSON.parse(run.stdout);

package/src/components/release-promote.test.ts

@@ -5,13 +5,13 @@
 
 import { describe, test, expect } from "vitest";
 import { contentDigest } from "../content-digest";
-import { makeRelease } from "../lifecycle/release-store";
+import { makeRelease, templateBytesDigest } from "../lifecycle/release-store";
 import type { DriverComponent } from "./driver";
 import { isImplicitRelease, pinReleaseTemplates, releaseArtifactMismatches, removePinnedTemplates, targetFiles, targetFor, writePinnedTemplates, RELEASE_TEMPLATES_DIR } from "./release-promote";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
 import { withTestDir } from "@intentius/chant-test-utils";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const prodTemplate = `{"env":"prod"}\n`;
@@ -63,6 +63,59 @@ describe("pinReleaseTemplates", () => {
     expect("errors" in absent && absent.errors[0]).toMatch(/are not on the chant\/lifecycle branch/);
   });
 
+  test("a target cut since #4155 points a chart at its recorded tree, which a reader of the release can trust", async () => {
+    const chartFile = "name: web\n";
+    const tgz = Buffer.from([0x1f, 0x8b, 0xff]).toString("base64");
+    const tgzDigest = templateBytesDigest(tgz, "base64");
+    const cut = makeRelease({
+      member: null,
+      commit: "c".repeat(40),
+      artifactDigests: [],
+      targets: [{
+        env: "prod",
+        params: [],
+        templates: [
+          { component: "web", path: "chart/Chart.yaml", digest: contentDigest(chartFile) },
+          { component: "web", path: "chart/charts/dep.tgz", digest: tgzDigest, encoding: "base64" },
+        ],
+        trees: [{ component: "web", path: "chart" }],
+      }],
+    });
+    const web: DriverComponent = {
+      name: "web",
+      deploy: [{ phase: "Deploy", steps: [
+        { kind: "helm-upgrade", release: "web", chart: "chart" },
+        { kind: "helm-upgrade", release: "remote", chart: "bitnami/nginx" },
+      ] }],
+    };
+    const bytes: Record<string, string> = { [contentDigest(chartFile)]: chartFile, [tgzDigest]: tgz };
+    const pinned = await pinReleaseTemplates([web], cut, cut.targets[0]!, async (d, encoding) => (encoding === "base64" && d !== tgzDigest ? null : bytes[d] ?? null));
+    if ("errors" in pinned) throw new Error(pinned.errors.join("\n"));
+    const step = pinned.components[0]!.deploy[0]!.steps[0] as unknown as { chart: string };
+    expect(step.chart).toMatch(/^\.chant\/release-templates\/[^/]+\/chart$/);
+    expect(pinned.files.map((f) => f.path.slice(step.chart.length + 1)).sort()).toEqual(["Chart.yaml", "charts/dep.tgz"]);
+    expect(pinned.files.find((f) => f.path.endsWith("dep.tgz"))).toMatchObject({ encoding: "base64", content: tgz });
+    // A chart named from a repository is not a local path the release records, and is left as written.
+    expect(pinned.components[0]!.deploy[0]!.steps[1]).toEqual(web.deploy[0]!.steps[1]);
+
+    await withTestDir(async (dir) => {
+      writePinnedTemplates(dir, pinned.files);
+      expect(readFileSync(join(dir, step.chart, "charts", "dep.tgz"))).toEqual(Buffer.from([0x1f, 0x8b, 0xff]));
+      removePinnedTemplates(dir, pinned.files);
+      expect(existsSync(join(dir, RELEASE_TEMPLATES_DIR))).toBe(false);
+    });
+
+    const edited = await pinReleaseTemplates([web], cut, cut.targets[0]!, async (d) => (d === contentDigest(chartFile) ? "name: edited\n" : bytes[d] ?? null));
+    expect("errors" in edited && edited.errors.join("\n")).toMatch(/template "chart\/Chart.yaml" hashes to .* refusing to deploy it/);
+  });
+
+  test("a target cut before #4155 (no trees) is pinned as then: the chart is read from the checkout", async () => {
+    const web: DriverComponent = { name: "api", deploy: [{ phase: "Deploy", steps: [{ kind: "helm-upgrade", release: "web", chart: "chart" }, ...api.deploy[1]!.steps] }] };
+    const pinned = await pinReleaseTemplates([web], release, prod, store(prodTemplate));
+    if ("errors" in pinned) throw new Error(pinned.errors.join("\n"));
+    expect(pinned.components[0]!.deploy[0]!.steps[0]).toEqual({ kind: "helm-upgrade", release: "web", chart: "chart" });
+  });
+
   test("targetFor names the environments a release was compiled for", () => {
     expect(targetFor(release, "prod")).toEqual({ target: prod });
     expect(targetFor(release, "qa")).toEqual({ error: expect.stringMatching(/has no target for "qa"; it was compiled for prod, staging/) });

package/src/components/release-promote.ts

@@ -11,14 +11,24 @@
  * under `.chant/release-templates/<digest>/` in the member's directory and the
  * step reads them from there. The path is relative and fixed by the digest,
  * so a gate approval bound to the promote's plan still matches on a re-run.
+ *
+ * A release cut since #4155 (a target with `trees`) records every local path
+ * a deploy step names (`recordedInputRefs`), directories file by file. A
+ * promote points each of them at the recorded copy: a directory is written
+ * under `.chant/release-templates/<digest>/<name>/`, its digest taken over its
+ * files the way a gate's directory digest is (`./deploy-inputs.ts`). A path
+ * outside the template fields that the release does not record, such as a
+ * chart named from a repository, is left as written. A target cut before
+ * #4155 is pinned as it was then: template fields only, other paths read from
+ * the checkout.
  */
 
 import { mkdirSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { contentDigest } from "../content-digest";
 import type { DriverComponent, DriverGate, DriverPhase, DriverStep } from "./driver";
-import { TEMPLATE_FIELDS, templateRefs } from "./release-compile";
-import type { Release, ReleaseTarget } from "../lifecycle/release-store";
+import { recordedFields, recordedInputRefs, TEMPLATE_FIELDS, templateRefs, type RecordedInputRef } from "./release-compile";
+import { templateBytesDigest, type Release, type ReleaseTarget } from "../lifecycle/release-store";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ReleaseRecord } from "../lifecycle/release-ledger";
 import type { BuildArchiveManifest } from "./verbs/build-archive";
 
@@ -29,9 +39,14 @@ export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
 export interface PinnedTemplate {
   /** Relative to the member's directory. */
   path: string;
+  /** The text, or the base64 of the bytes under `encoding: "base64"`. */
   content: string;
+  encoding?: "base64";
 }
 
+/** Reads a recorded template's stored copy by digest: its text, or its base64 under `base64`. */
+export type TemplateReader = (digest: string, encoding?: "base64") => Promise<string | null>;
+
 /** The release's target for `env`, or an error naming the environments it has. */
 export function targetFor(release: Release, env: string): { target: ReleaseTarget } | { error: string } {
   const target = release.targets.find((t) => t.env === env);
@@ -65,37 +80,45 @@ export async function pinReleaseTemplates(
   components: readonly DriverComponent[],
   release: Release,
   target: ReleaseTarget,
-  readTemplate: (digest: string) => Promise<string | null>,
+  readTemplate: TemplateReader,
 ): Promise<{ components: DriverComponent[]; files: PinnedTemplate[] } | { errors: string[] }> {
   const errors: string[] = [];
   const files: PinnedTemplate[] = [];
   const out: DriverComponent[] = [];
+  // #4155: a target with `trees` records every deploy input; one without was cut before and records template fields only.
+  const full = target.trees !== undefined;
   for (const component of components) {
     const replace = new Map<string, string>();
-    for (const ref of templateRefs(component)) {
+    const refs: RecordedInputRef[] = full ? recordedInputRefs(component) : templateRefs(component).map((r) => ({ ...r, required: true }));
+    for (const ref of refs) {
       if (replace.has(ref.value)) continue;
+      const dir = ref.path.replace(/\/+$/, "");
+      const tree = full ? target.trees!.find((t) => t.component === component.name && t.path === dir) : undefined;
+      if (tree) {
+        const pinned = await pinTree(component.name, tree.path, target, readTemplate);
+        if ("errors" in pinned) errors.push(...pinned.errors);
+        else {
+          files.push(...pinned.files);
+          replace.set(ref.value, pinned.path);
+        }
+        continue;
+      }
       const recorded = target.templates.find((t) => t.component === component.name && t.path === ref.path);
       if (!recorded) {
+        if (!ref.required) continue;
         errors.push(
           `component "${component.name}" reads ${ref.field} "${ref.value}", which release ${release.releaseDigest} does not record for "${target.env}"; ` +
             `this checkout's deploy is not the one the release was compiled from (commit ${release.commit.slice(0, 12)})`,
         );
         continue;
       }
-      const content = await readTemplate(recorded.digest);
-      if (content === null) {
-        errors.push(`component "${component.name}": the bytes of template "${ref.path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
-        continue;
-      }
-      const got = contentDigest(content);
-      if (got !== recorded.digest) {
-        errors.push(
-          `component "${component.name}": template "${ref.path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it`,
-        );
+      const read = await readChecked(component.name, ref.path, recorded, target, readTemplate);
+      if ("error" in read) {
+        errors.push(read.error);
         continue;
       }
       const path = join(RELEASE_TEMPLATES_DIR, recorded.digest.replace(/:/g, "_"), basename(ref.path));
-      files.push({ path, content });
+      files.push({ path, content: read.content, ...(recorded.encoding ? { encoding: recorded.encoding } : {}) });
       replace.set(ref.value, path);
     }
     const rewrite = (phase: DriverPhase): DriverPhase => ({
@@ -104,7 +127,7 @@ export async function pinReleaseTemplates(
         if (isPhase(step)) return rewrite(step);
         if (isGate(step)) return step;
         const next: DriverStep = { ...step };
-        for (const field of TEMPLATE_FIELDS) {
+        for (const field of full ? recordedFields(step.kind) : TEMPLATE_FIELDS) {
           const v = next[field];
           if (typeof v === "string" && replace.has(v)) next[field] = replace.get(v);
           else if (Array.isArray(v)) next[field] = v.map((x) => (typeof x === "string" && replace.has(x) ? replace.get(x) : x));
@@ -117,6 +140,51 @@ export async function pinReleaseTemplates(
   return errors.length > 0 ? { errors } : { components: out, files };
 }
 
+/** One recorded template's stored copy, checked against its digest. */
+async function readChecked(
+  component: string | null,
+  path: string,
+  recorded: ReleaseTarget["templates"][number],
+  target: ReleaseTarget,
+  readTemplate: TemplateReader,
+): Promise<{ content: string } | { error: string }> {
+  const who = component === null ? "" : `component "${component}": `;
+  const content = await readTemplate(recorded.digest, recorded.encoding);
+  if (content === null) return { error: `${who}the bytes of template "${path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again` };
+  const got = templateBytesDigest(content, recorded.encoding);
+  if (got !== recorded.digest) {
+    return { error: `${who}template "${path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it` };
+  }
+  return { content };
+}
+
+/**
+ * A recorded directory's files, under `.chant/release-templates/<digest>/<name>/`
+ * (#4155). The digest is taken over the files' paths from the directory and
+ * their bytes, as a gate's directory digest is, so the path names the tree.
+ */
+async function pinTree(
+  component: string,
+  dir: string,
+  target: ReleaseTarget,
+  readTemplate: TemplateReader,
+): Promise<{ path: string; files: PinnedTemplate[] } | { errors: string[] }> {
+  const prefix = `${dir}/`;
+  const entries = target.templates.filter((t) => t.component === component && t.path.startsWith(prefix));
+  const errors: string[] = [];
+  const read: Array<{ rel: string; content: string; encoding?: "base64"; digest: string }> = [];
+  for (const e of entries) {
+    const got = await readChecked(component, e.path, e, target, readTemplate);
+    if ("error" in got) errors.push(got.error);
+    else read.push({ rel: e.path.slice(prefix.length), content: got.content, digest: e.digest, ...(e.encoding ? { encoding: e.encoding } : {}) });
+  }
+  if (errors.length > 0) return { errors };
+  read.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  const digest = computePlanDigest("directory", read.map(({ rel, digest }) => ({ path: rel, digest })));
+  const path = join(RELEASE_TEMPLATES_DIR, digest.replace(/:/g, "_"), basename(dir));
+  return { path, files: read.map((r) => ({ path: join(path, r.rel), content: r.content, ...(r.encoding ? { encoding: r.encoding } : {}) })) };
+}
+
 /**
  * The files a release's target records, read back by digest and checked, for
  * `chant release export` (#4046). A project with no components has no deploy
@@ -129,7 +197,7 @@ export async function pinReleaseTemplates(
 export async function targetFiles(
   release: Release,
   target: ReleaseTarget,
-  readTemplate: (digest: string) => Promise<string | null>,
+  readTemplate: TemplateReader,
 ): Promise<{ files: PinnedTemplate[] } | { errors: string[] }> {
   const errors: string[] = [];
   const files: PinnedTemplate[] = [];
@@ -139,12 +207,12 @@ export async function targetFiles(
       errors.push(`${who}template "${t.path}" is not a path inside the member's directory; refusing to write it`);
       continue;
     }
-    const content = await readTemplate(t.digest);
+    const content = await readTemplate(t.digest, t.encoding);
     if (content === null) {
       errors.push(`${who}the bytes of template "${t.path}" (${t.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
       continue;
     }
-    const got = contentDigest(content);
+    const got = templateBytesDigest(content, t.encoding);
     if (got !== t.digest) {
       errors.push(`${who}template "${t.path}" hashes to ${got}, but release ${release.releaseDigest} records ${t.digest} for "${target.env}"; refusing to write it`);
       continue;
@@ -154,7 +222,7 @@ export async function targetFiles(
       if (same.content !== content) errors.push(`two components record different bytes at "${t.path}" for "${target.env}", so they can't both be written there`);
       continue;
     }
-    files.push({ path: t.path, content });
+    files.push({ path: t.path, content, ...(t.encoding ? { encoding: t.encoding } : {}) });
   }
   return errors.length > 0 ? { errors } : { files };
 }
@@ -164,7 +232,7 @@ export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate
   for (const f of files) {
     const full = join(dir, f.path);
     mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, f.content);
+    writeFileSync(full, f.encoding === "base64" ? Buffer.from(f.content, "base64") : f.content);
   }
 }
 
@@ -175,7 +243,9 @@ export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate
  * again from the release.
  */
 export function removePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
-  for (const f of files) rmSync(dirname(join(dir, f.path)), { recursive: true, force: true });
+  // Each file sits under `.chant/release-templates/<digest>/`, a recorded tree's deeper; that digest directory goes.
+  const prefix = RELEASE_TEMPLATES_DIR.split("/").length;
+  for (const f of files) rmSync(join(dir, ...f.path.split(/[\\/]/).slice(0, prefix + 1)), { recursive: true, force: true });
   const root = join(dir, RELEASE_TEMPLATES_DIR);
   try {
     if (readdirSync(root).length === 0) rmdirSync(root);

package/src/components/verbs/bom-writer.ts

@@ -72,7 +72,7 @@ export interface BomPackage {
   /** Version string, when known. Omitted for resources with no version concept (e.g. a CFN resource). */
   version?: string;
   /** Package manager / ecosystem this entry came from (e.g. "npm", "maven"), surfaced in SPDX's `externalRefs`/CycloneDX's `purl` when derivable. */
-  type?: "npm" | "maven" | "config" | "external-reference";
+  type?: "npm" | "maven" | "cargo" | "config" | "external-reference";
   /** Package URL (purl), when derivable — e.g. `pkg:npm/left-pad@1.3.0`. */
   purl?: string;
   /** SPDX download location, when known. Defaults to `"NOASSERTION"` per the SPDX spec's requirement that every package declare one. */

package/src/components/verbs/lockfile-sbom-generator.test.ts

@@ -11,6 +11,7 @@ import { describe, expect, it, afterEach } from "vitest";
 import {
   parseNpmPackageLock,
   parsePomXml,
+  parseCargoLock,
   createLockfileSbomGenerator,
   sbomOutputPath,
 } from "./lockfile-sbom-generator";
@@ -193,3 +194,38 @@ describe("createLockfileSbomGenerator (#613) — hermetic SbomGenerator backend"
     expect(docA.bytes).toBe(docB.bytes);
   });
 });
+
+describe("parseCargoLock (#4168)", () => {
+  const LOCK = [
+    "version = 4",
+    "",
+    "[[package]]",
+    'name = "app"',
+    'version = "0.1.0"',
+    "dependencies = [",
+    ' "serde",',
+    ' "tokio 1.40.0",',
+    "]",
+    "",
+    "[[package]]",
+    'name = "serde"',
+    'version = "1.0.210"',
+    'source = "registry+https://github.com/rust-lang/crates.io-index"',
+    "",
+    "[[package]]",
+    'name = "tokio"',
+    'version = "1.40.0"',
+    'source = "registry+https://github.com/rust-lang/crates.io-index"',
+    "dependencies = [",
+    ' "pin-project-lite",',
+    "]",
+    "",
+  ].join("\n");
+
+  it("lists every package with a source, with its purl and dependencies, and leaves out the workspace's own crates", () => {
+    expect(parseCargoLock(LOCK)).toEqual([
+      { name: "serde", version: "1.0.210", type: "cargo", purl: "pkg:cargo/serde@1.0.210", dependsOn: undefined },
+      { name: "tokio", version: "1.40.0", type: "cargo", purl: "pkg:cargo/tokio@1.40.0", dependsOn: ["pin-project-lite"] },
+    ]);
+  });
+});

package/src/components/verbs/lockfile-sbom-generator.ts

@@ -148,6 +148,44 @@ export function parsePomXml(content: string): BomPackage[] {
   return packages.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// ── Cargo.lock (Rust, #4168 decision 12) ────────────────────────────────────
+
+/**
+ * Parse a `Cargo.lock` (version 3 or 4) into a flat `BomPackage[]`: one
+ * entry per `[[package]]` with a `source`, so the workspace's own crates,
+ * which have none, are left out as the npm parser leaves out the root.
+ * A dependency is named `name` or `name version` in the lock; only the name
+ * is kept. A small line reader, not a TOML parser: the lock is written by
+ * cargo in one fixed shape.
+ */
+export function parseCargoLock(content: string): BomPackage[] {
+  const seen = new Map<string, BomPackage>();
+  const blocks = content.split(/^\[\[package\]\]\s*$/m).slice(1);
+  for (const block of blocks) {
+    const body = block.split(/^\[/m)[0] ?? "";
+    const field = (key: string) => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m").exec(body)?.[1];
+    const name = field("name");
+    const version = field("version");
+    if (!name || field("source") === undefined) continue;
+    const deps = /^dependencies\s*=\s*\[([\s\S]*?)\]/m.exec(body)?.[1];
+    const dependsOn = deps ? [...deps.matchAll(/"([^"\s]+)[^"]*"/g)].map((m) => m[1]!) : [];
+    const key = `${name}@${version ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.set(key, {
+      name,
+      version,
+      type: "cargo",
+      purl: version ? `pkg:cargo/${encodeURIComponent(name)}@${version}` : undefined,
+      dependsOn: dependsOn.length ? [...new Set(dependsOn)] : undefined,
+    });
+  }
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name) || (a.version ?? "").localeCompare(b.version ?? ""));
+}
+
+/** Each lockfile kind's parser and file name. */
+export const LOCKFILE_PARSERS = { npm: parseNpmPackageLock, maven: parsePomXml, cargo: parseCargoLock } as const;
+export const LOCKFILE_NAMES = { npm: "package-lock.json", maven: "pom.xml", cargo: "Cargo.lock" } as const;
+
 // ── hermetic SbomGenerator backend ───────────────────────────────────────────
 
 export interface LockfileSbomGeneratorOptions {
@@ -158,8 +196,8 @@ export interface LockfileSbomGeneratorOptions {
 }
 
 /** Locate the first readable lockfile/manifest under `dir` this generator knows how to parse, in preference order (npm before Maven — most chant components are Node-first). Returns `undefined` if none is found. */
-function findManifest(dir: string): { kind: "npm" | "maven"; path: string } | undefined {
-  for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"]] as const) {
+function findManifest(dir: string): { kind: "npm" | "maven" | "cargo"; path: string } | undefined {
+  for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"], ["cargo", "Cargo.lock"]] as const) {
     const candidate = join(dir, filename);
     try {
       readFileSync(candidate, "utf-8");
@@ -195,13 +233,13 @@ export function createLockfileSbomGenerator(options: LockfileSbomGeneratorOption
     const manifest = findManifest(dir);
     if (!manifest) {
       throw new Error(
-        `no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml) — ` +
+        `no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml, Cargo.lock) — ` +
           `the hermetic lockfile SBOM backend requires a lockfile on disk; use the deep-scan path (#610) for images with no lockfile`,
       );
     }
     const content = readFileSync(manifest.path, "utf-8");
-    const packages = manifest.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
-    const generatorName = manifest.kind === "npm" ? "chant-lockfile-sbom/package-lock.json" : "chant-lockfile-sbom/pom.xml";
+    const packages = LOCKFILE_PARSERS[manifest.kind](content);
+    const generatorName = `chant-lockfile-sbom/${LOCKFILE_NAMES[manifest.kind]}`;
 
     const doc = writeBom(
       format,