@intentius/chant 0.124.32 → 0.124.34

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-gate.test.ts

@@ -13,6 +13,7 @@ import {
   emptyVerifier,
   gateNamesOf,
   planReleaseChangeSet,
+  planReleaseSet,
   provisionalMembers,
   RELEASE_GATE_OP,
 } from "./release-gate";
@@ -162,6 +163,52 @@ describe("planReleaseChangeSet", () => {
   });
 });
 
+describe("planReleaseSet: a dependent plans against its upstream's planned outputs (#4168 step 4)", () => {
+  const r1 = release(sha("7"));
+  const reg = () => {
+    const r = registry();
+    r.register({
+      kind: "tf",
+      async run() { return {}; },
+      async plan(_ctx: unknown, input: { name: string; vpc?: unknown }) {
+        return {
+          member: input.name,
+          planDigest: sha(input.vpc === "vpc-new" ? "b" : input.vpc === undefined ? "c" : "a"),
+          outputs: input.name === "net" ? { known: { id: "vpc-new" }, unknown: ["arn"] } : undefined,
+        };
+      },
+      async outputs() { return { id: "vpc-old", arn: "arn:old" }; },
+    } as never);
+    return r;
+  };
+  const net: DriverComponent = { name: "net", deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "net" }] }] };
+  const svc = (ref: string): DriverComponent => ({
+    name: "svc",
+    dependsOn: ["net"],
+    deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "tf", name: "svc", vpc: { stackOutput: { stack: "net", name: ref } } }] }],
+  });
+
+  test("an upstream the promote plans is read from its plan, and the read is kept", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("id"), net], digests: new Map(), registry: reg(), current: new Map() });
+    expect(set.doc.members.find((m) => m.member === "svc")?.planDigest).toBe(sha("b"));
+    expect(set.reads.svc).toEqual({ net: { id: "vpc-new" } });
+    expect(set.plannedOutputs).toEqual({ net: ["id"] });
+    expect(set.unknownInputs).toBeUndefined();
+  });
+
+  test("an output the upstream's plan can't say is an unknown input", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("arn"), net], digests: new Map(), registry: reg(), current: new Map() });
+    expect(set.unknownInputs).toEqual({ svc: ["net.arn"] });
+  });
+
+  test("an upstream outside the promote is read as it stands", async () => {
+    const set = await planReleaseSet({ release: r1, env: "prod", components: [svc("id"), net], digests: new Map(), registry: reg(), current: new Map(), only: new Set(["svc"]), seededOutputs: { net: { id: "vpc-old" } } });
+    expect(set.doc.members.map((m) => m.member)).toEqual(["svc"]);
+    expect(set.reads.svc).toEqual({ net: { id: "vpc-old" } });
+    expect(set.plannedOutputs).toBeUndefined();
+  });
+});
+
 describe("empty change sets", () => {
   const r1 = release(sha("7"));
   const emptyDoc = (): ChangeSetDocument =>

package/src/components/release-gate.ts

@@ -39,6 +39,14 @@
  * planned by that capability, as a pull request's plan is. A plan that
  * returns no change-set part is a hole, since nothing says what it changes.
  *
+ * A dependency the promote also deploys is read from its plan, not from the
+ * estate (#4168 step 4, the rule #3999 gave a pull request): a dependent is
+ * planned against the outputs its upstream's plan says it will expose, and a
+ * reference the plan can't say is listed in `unknownInputs`. Any other
+ * dependency is read as it stands. What each component was planned against is
+ * kept in `reads`, so the promote can hold it back when an upstream applies
+ * as another value (`./promote-rounds.ts`).
+ *
  * Any other component is a `chant` member compared with what the
  * environment runs now: its latest deploy record and the release that record
  * names. The artifact digest, each template the release's target records for
@@ -52,8 +60,8 @@
  * recorded since (#4035): its record names what ran before that run.
  */
 
-import type { CapabilityRegistry } from "./capability";
-import { deployContext, resolveComponentGraph, resolveStepInput, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
+import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name";
 import { capabilitySteps, planContext, readComponentOutputs } from "./wave-plan";
@@ -123,6 +131,23 @@ export interface ReleaseChangeSetInput {
   seededOutputs?: Record<string, Record<string, unknown>>;
   /** The chant version to record in the document. */
   chant?: string;
+  /**
+   * Plan only these components (a later round or wave, ./promote-rounds.ts).
+   * The others are not planned; a dependency among them is read from
+   * `seededOutputs`, which then holds what the run left. Default: every one.
+   */
+  only?: ReadonlySet<string>;
+}
+
+/** A release's change set for an environment, and what each component was planned against. */
+export interface ReleasePlan {
+  doc: ChangeSetDocument;
+  /** Per planned component, the outputs of its dependencies as its plan read them. */
+  reads: Record<string, Record<string, Record<string, unknown>>>;
+  /** Per dependency read from its plan, the names of the outputs the plan knows, sorted. Absent when none. */
+  plannedOutputs?: Record<string, string[]>;
+  /** Per component, the references to a promoted upstream that no value stands for until it applies, sorted. Absent when none. */
+  unknownInputs?: Record<string, string[]>;
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -240,65 +265,105 @@ export function chantComponentPart(input: {
  * that fails to plan: it becomes a failed member.
  */
 export async function planReleaseChangeSet(input: ReleaseChangeSetInput): Promise<ChangeSetDocument> {
+  return (await planReleaseSet(input)).doc;
+}
+
+/**
+ * {@link planReleaseChangeSet}, with what each component read. Components are
+ * planned a wave at a time, so a dependency the promote deploys has planned
+ * before its dependents read its outputs.
+ */
+export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<ReleasePlan> {
   const { release, env, registry } = input;
   const components = [...input.components];
   const byName = new Map(components.map((c) => [c.name, c]));
   const outputs: Record<string, Record<string, unknown>> = { ...(input.seededOutputs ?? {}) };
   const read = new Set(Object.keys(outputs));
   const parts: ChangeSetPart[] = [];
-  const { order } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
-  for (const name of order) {
-    const component = byName.get(name)!;
-    const digest = input.digests.get(name) ?? "";
-    const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
-    if (plannable.length === 0) {
-      parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
-      continue;
-    }
-    const ctx = deployContext({ env }, name);
-    try {
-      for (const dep of component.dependsOn ?? []) {
-        if (read.has(dep) || !byName.has(dep)) continue;
-        read.add(dep);
-        const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
-        if (found) outputs[dep] = found;
+  const plannedBy = new Map<string, PlannedOutputs | undefined>();
+  const planned: Record<string, string[]> = {};
+  const unknownInputs: Record<string, string[]> = {};
+  const reads: ReleasePlan["reads"] = {};
+  const inPlan = (name: string): boolean => input.only === undefined || input.only.has(name);
+  const isPlannable = (c: DriverComponent): boolean =>
+    capabilitySteps(c.deploy).some((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+  const { waves } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  for (const wave of waves) {
+    const planning = wave.filter(inPlan);
+    for (const name of planning) {
+      const component = byName.get(name)!;
+      const digest = input.digests.get(name) ?? "";
+      const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+      if (plannable.length === 0) {
+        parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
+        continue;
       }
-      for (const step of plannable) {
-        const { kind, ...rest } = step;
-        const planned = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
-        parts.push(
-          planned.changeSet ?? {
-            member: {
-              member: planned.member,
-              lexicon: "chant",
-              planner: "chant",
-              status: "planned",
-              planDigest: planned.planDigest,
-              holes: [{ address: planned.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+      const ctx = deployContext({ env }, name);
+      try {
+        for (const dep of component.dependsOn ?? []) {
+          if (read.has(dep) || !byName.has(dep)) continue;
+          read.add(dep);
+          // A dependency this promote plans exposes what its plan says (#3999).
+          if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
+            const known = plannedBy.get(dep)?.known ?? {};
+            outputs[dep] = { ...known };
+            planned[dep] = Object.keys(known).sort();
+            continue;
+          }
+          const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
+          if (found) outputs[dep] = found;
+        }
+        reads[name] = Object.fromEntries((component.dependsOn ?? []).filter((d) => d in outputs).map((d) => [d, structuredClone(outputs[d])]));
+        const unknown = new Set<string>();
+        let exposes: PlannedOutputs | undefined;
+        for (const step of plannable) {
+          const { kind, ...rest } = step;
+          for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish) unknown.add(r.ref);
+          const result = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
+          if (result.outputs) exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
+          parts.push(
+            result.changeSet ?? {
+              member: {
+                member: result.member,
+                lexicon: "chant",
+                planner: "chant",
+                status: "planned",
+                planDigest: result.planDigest,
+                holes: [{ address: result.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+              },
+              entries: [],
             },
-            entries: [],
+          );
+        }
+        plannedBy.set(name, exposes);
+        if (unknown.size > 0) unknownInputs[name] = [...unknown].sort();
+      } catch (err) {
+        plannedBy.set(name, undefined);
+        parts.push({
+          member: {
+            member: name,
+            lexicon: "chant",
+            planner: "chant",
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            planDigest: null,
+            holes: [],
           },
-        );
+          entries: [],
+        });
       }
-    } catch (err) {
-      parts.push({
-        member: {
-          member: name,
-          lexicon: "chant",
-          planner: "chant",
-          status: "failed",
-          error: err instanceof Error ? err.message : String(err),
-          planDigest: null,
-          holes: [],
-        },
-        entries: [],
-      });
     }
   }
-  return composeChangeSet(parts, {
+  const doc = composeChangeSet(parts, {
     ...(input.chant !== undefined ? { chant: input.chant } : {}),
     planned: { releaseDigest: release.releaseDigest, environment: env },
   });
+  return {
+    doc,
+    reads,
+    ...(Object.keys(planned).length > 0 ? { plannedOutputs: planned } : {}),
+    ...(Object.keys(unknownInputs).length > 0 ? { unknownInputs } : {}),
+  };
 }
 
 /** The members a release gate refuses: provisional ones, which no approval of the document covers (`change-set.mdx`). */

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/) });