@intentius/chant-lexicon-pulumi 0.124.55 → 0.124.57

package/src/planned-output-changes.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Which stack outputs a preview changes (#4635), over the recorded previews
+ * in `testdata/pulumi-outputs` (pulumi 3.272.0, the plunge corpus's aws-ts
+ * program on floci, #4475) and copies of their steps edited in the test.
+ * No engine runs.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { pulumiPreviewPart, type PulumiStep } from "./change-set";
+import { pulumiMemberPlannedOutputs } from "./member-outputs";
+import { pulumiPlannedOutputChanges } from "./planned-output-changes";
+
+const dir = join(import.meta.dirname, "testdata", "pulumi-outputs");
+const read = (f: string) => JSON.parse(readFileSync(join(dir, f), "utf8")) as { steps: PulumiStep[] };
+const exported = JSON.parse(readFileSync(join(dir, "stack-export.json"), "utf8")) as unknown;
+const partOf = (preview: { steps: PulumiStep[] }, targeted = false) => pulumiPreviewPart({ member: "aws", preview, prior: exported, ...(targeted ? { targeted } : {}) });
+
+describe("the recorded previews", () => {
+  test("a replaced VPC moves its id, the security group's, the deleted parameter's name and the deleted queue's URL", () => {
+    const r = pulumiPlannedOutputChanges({ part: partOf(read("preview-replaced.json")), exported });
+    expect(r.unknown).toEqual(["securityGroupId", "vpcId", "vpcParameterName", "workerQueueUrls"]);
+    expect(r.outputs.find((o) => o.output === "vpcId")).toEqual({ output: "vpcId", verdict: "changing", because: "aws:ec2/vpc:Vpc::main.id (replace)" });
+    expect(r.outputs.find((o) => o.output === "workerQueueUrls")).toMatchObject({ verdict: "changing", because: "aws:sqs/queue:Queue::worker-2.id (delete)" });
+    // The events queue updates in place: its id (its URL) stays.
+    expect(r.outputs.find((o) => o.output === "eventsQueueUrl")).toMatchObject({ verdict: "unchanged", because: "aws:sqs/queue:Queue::events.id (update)" });
+    expect(r.known.siteBucketName).toBe("rec-ts-site");
+    expect(r.outputs.map((o) => o.output)).not.toContain("dbPasswordValue");
+  });
+
+  test("a settled preview changes nothing", () => {
+    expect(pulumiPlannedOutputChanges({ part: partOf(read("preview-settled.json")), exported }).unknown).toEqual([]);
+  });
+
+  test("pulumiMemberPlannedOutputs takes the trace when the preview plans no stack outputs", () => {
+    const preview = read("preview-replaced.json");
+    const planned = pulumiMemberPlannedOutputs("aws", { part: partOf(preview), preview, exported });
+    expect(planned.unknown).toEqual(["securityGroupId", "vpcId", "vpcParameterName", "workerQueueUrls"]);
+    expect(planned.outputChanges?.length).toBe(12);
+    // With no export there is nothing to trace and no output to name.
+    expect(pulumiMemberPlannedOutputs("aws", { part: partOf(preview), preview })).toMatchObject({ known: {}, unknown: [] });
+  });
+});
+
+describe("edited from the recording", () => {
+  const settled = () => structuredClone(read("preview-settled.json"));
+  const at = (p: { steps: PulumiStep[] }, tail: string) => p.steps.find((s) => s.urn?.endsWith(tail))!;
+
+  test("an update whose diff names the input an output reads moves it", () => {
+    const p = settled();
+    const s = at(p, "aws:s3/bucket:Bucket::site-bucket");
+    s.op = "update";
+    s.newState = { ...s.newState!, inputs: { ...(s.newState!.inputs as object), bucket: "rec-ts-site-2" } };
+    s.diffReasons = ["bucket"];
+    const r = pulumiPlannedOutputChanges({ part: partOf(p), exported });
+    // siteBucketName matches the bucket's id too, and an id stays through an in-place update; bucket is the input the diff names.
+    expect(r.outputs.find((o) => o.output === "siteBucketName")).toMatchObject({ verdict: "changing", because: "aws:s3/bucket:Bucket::site-bucket.bucket (update)" });
+  });
+
+  test("an output only a provider-computed property holds may move on an update, so it is changing", () => {
+    const exp = structuredClone(exported) as { deployment: { resources: Array<Record<string, unknown>> } };
+    const stack = exp.deployment.resources.find((r) => r.type === "pulumi:pulumi:Stack")!;
+    const queue = exp.deployment.resources.find((r) => String(r.urn).endsWith("Queue::events"))!;
+    (queue.outputs as Record<string, unknown>).computedMark = "mark-0042";
+    (stack.outputs as Record<string, unknown>).eventsMark = "mark-0042";
+    const r = pulumiPlannedOutputChanges({ part: pulumiPreviewPart({ member: "aws", preview: read("preview-replaced.json"), prior: exp }), exported: exp });
+    expect(r.outputs.find((o) => o.output === "eventsMark")).toEqual({ output: "eventsMark", verdict: "changing", because: "aws:sqs/queue:Queue::events.computedMark (update)" });
+  });
+
+  test("an output no property holds is untraced, so unknown", () => {
+    const exp = structuredClone(exported) as { deployment: { resources: Array<Record<string, unknown>> } };
+    const stack = exp.deployment.resources.find((r) => r.type === "pulumi:pulumi:Stack")!;
+    (stack.outputs as Record<string, unknown>).sitePattern = "arn:aws:s3:::rec-ts-site/*";
+    const r = pulumiPlannedOutputChanges({ part: pulumiPreviewPart({ member: "aws", preview: read("preview-replaced.json"), prior: exp }), exported: exp });
+    expect(r.outputs.find((o) => o.output === "sitePattern")).toEqual({ output: "sitePattern", verdict: "untraced" });
+    expect(r.unknown).toContain("sitePattern");
+  });
+
+  test("a resource a targeted preview does not list is left alone; an untargeted one that leaves it out may register it again", () => {
+    const p = settled();
+    p.steps = p.steps.filter((s) => !s.urn?.endsWith("aws:ec2/vpc:Vpc::main"));
+    expect(pulumiPlannedOutputChanges({ part: partOf(p, true), exported, targeted: true }).outputs.find((o) => o.output === "vpcId")?.verdict).toBe("unchanged");
+    expect(pulumiPlannedOutputChanges({ part: partOf(p), exported }).outputs.find((o) => o.output === "vpcId")?.verdict).toBe("changing");
+  });
+});

package/src/planned-output-changes.ts

@@ -0,0 +1,141 @@
+/**
+ * Which of a stack's outputs its preview changes (#4635). A real `pulumi
+ * preview --json` plans no stack outputs (recorded, #4475), so until this
+ * module every output of a stack with any change was unknown, and every
+ * stack reading any of them waited for the `up`. Here each output the last
+ * deployment holds is traced, by value, to the resource properties in the
+ * export that hold the same value, and the preview's entry for each such
+ * resource says whether the value can move:
+ *
+ * | the resource's entry | the property | verdict |
+ * |---|---|---|
+ * | replace, delete, or a `mayAppear` update | any | changes |
+ * | update | an input the diff names, or one that is unknown | changes |
+ * | update | an input the diff leaves alone; `id`, `arn` or `urn` | stable |
+ * | update | any other output (a provider-computed `version`) | may change |
+ * | no-op, read, or no entry in a targeted preview | any | stable |
+ *
+ * An output is changing when one of its matches changes, or when every
+ * match only may change; it is unchanged, with the export's value, when no
+ * match changes and one is stable. An output no property matches (one the
+ * program computed, such as `` `${bucket.arn}/*` ``), or an object, is
+ * untraced, and so unknown while the stack has changes. A list traces each
+ * string in it. Strings shorter than four characters match nothing, so a
+ * `"1"` or a `"true"` traces no output. Secret outputs are left out, as
+ * everywhere: chant reads outputs blind.
+ *
+ * The trace runs only when the preview plans no stack outputs and has
+ * changes; core's `member-outputs` and `pulumi-up`'s plan then take its
+ * unchanged outputs as known and the rest as unknown, so a stack reading
+ * through `StackReference` (#4547) an output the change moves is held until
+ * the producer applied and the reader is previewed again, and one reading
+ * only unchanged outputs plans now.
+ */
+import type { ChangeSetEntry, ChangeSetPart } from "@intentius/chant/change-set";
+import { isPulumiNodeless } from "@intentius/chant/pulumi-urn";
+import { pulumiExportedStackOutputs } from "./stack-outputs";
+import { isObject, isSecret } from "./values";
+
+/** One output's verdict, and the resource property that decided it. */
+export interface PulumiOutputChange {
+  output: string;
+  verdict: "changing" | "unchanged" | "untraced";
+  /** The deciding match: `<urn tail>.<property>` and the resource's action. Absent when untraced. */
+  because?: string;
+}
+
+/** The trace of every output the export holds that is not secret, by name. */
+export interface PulumiPlannedOutputChanges {
+  outputs: PulumiOutputChange[];
+  /** Unchanged outputs with the export's value. */
+  known: Record<string, unknown>;
+  /** Changing and untraced outputs. */
+  unknown: string[];
+}
+
+/** Properties that stay put through an in-place update. */
+const STABLE_OUTPUTS = new Set(["id", "arn", "urn"]);
+
+type Verdict = "changes" | "stable" | "maybe";
+
+interface Holder {
+  urn: string;
+  prop: string;
+  input: boolean;
+}
+
+const tailOf = (urn: string): string => urn.split("::").slice(2).join("::") || urn;
+
+/** Every (resource, property) of the export holding a string worth matching, by value. */
+function holdersByValue(exported: unknown): Map<string, Holder[]> {
+  const deployment = isObject(exported) && isObject(exported.deployment) ? exported.deployment : {};
+  const resources = Array.isArray(deployment.resources) ? deployment.resources : [];
+  const by = new Map<string, Holder[]>();
+  const add = (value: unknown, h: Holder) => {
+    if (typeof value !== "string" || value.length < 4) return;
+    const list = by.get(value) ?? [];
+    list.push(h);
+    by.set(value, list);
+  };
+  for (const r of resources) {
+    if (!isObject(r) || typeof r.urn !== "string" || typeof r.type !== "string") continue;
+    if (r.custom !== true || isPulumiNodeless(r.type)) continue;
+    const inputs = isObject(r.inputs) ? r.inputs : {};
+    add(r.id, { urn: r.urn, prop: "id", input: false });
+    for (const [k, v] of Object.entries(isObject(r.outputs) ? r.outputs : {})) {
+      if (isSecret(v)) continue;
+      add(v, { urn: r.urn, prop: k, input: k in inputs });
+    }
+  }
+  return by;
+}
+
+function verdictOf(h: Holder, entry: ChangeSetEntry | undefined, targeted: boolean): Verdict {
+  if (!entry) return targeted ? "stable" : "changes";
+  if (entry.mayAppear === true || entry.action === "replace" || entry.action === "delete" || entry.action === "forget") return "changes";
+  if (entry.action !== "update") return "stable";
+  const attr = entry.attributes.find((a) => a.path === h.prop);
+  if (attr) return "changes";
+  if (h.input || STABLE_OUTPUTS.has(h.prop)) return "stable";
+  return "maybe";
+}
+
+/**
+ * Trace each of the export's stack outputs through the member's part (the
+ * change set its preview became). `targeted` says the preview was narrowed
+ * with `--target`, so a resource it did not list is not touched by it.
+ */
+export function pulumiPlannedOutputChanges(input: { part: ChangeSetPart; exported: unknown; targeted?: boolean }): PulumiPlannedOutputChanges {
+  const byUrn = new Map<string, ChangeSetEntry>();
+  for (const e of input.part.entries) if (!byUrn.has(e.address)) byUrn.set(e.address, e);
+  const holders = holdersByValue(input.exported);
+  const targeted = input.targeted === true;
+
+  const traceString = (value: string): { verdict: PulumiOutputChange["verdict"]; because?: string } => {
+    const list = holders.get(value) ?? [];
+    if (list.length === 0) return { verdict: "untraced" };
+    const judged = list.map((h) => ({ h, v: verdictOf(h, byUrn.get(h.urn), targeted), action: byUrn.get(h.urn)?.action ?? "unlisted" }));
+    const why = (j: (typeof judged)[number]) => `${tailOf(j.h.urn)}.${j.h.prop} (${j.action})`;
+    const changes = judged.find((j) => j.v === "changes");
+    if (changes) return { verdict: "changing", because: why(changes) };
+    const stable = judged.find((j) => j.v === "stable");
+    if (stable) return { verdict: "unchanged", because: why(stable) };
+    return { verdict: "changing", because: why(judged[0]!) };
+  };
+
+  const outputs: PulumiOutputChange[] = [];
+  const known: Record<string, unknown> = {};
+  for (const o of pulumiExportedStackOutputs(input.exported)) {
+    if (o.secret) continue;
+    let traced: { verdict: PulumiOutputChange["verdict"]; because?: string };
+    if (typeof o.value === "string") traced = traceString(o.value);
+    else if (Array.isArray(o.value) && o.value.length > 0 && o.value.every((v) => typeof v === "string")) {
+      const each = (o.value as string[]).map(traceString);
+      traced = each.find((t) => t.verdict === "changing") ?? each.find((t) => t.verdict === "untraced") ?? each[0]!;
+    } else traced = { verdict: "untraced" };
+    outputs.push({ output: o.name, verdict: traced.verdict, ...(traced.because ? { because: traced.because } : {}) });
+    if (traced.verdict === "unchanged") known[o.name] = o.value;
+  }
+  outputs.sort((a, b) => (a.output < b.output ? -1 : a.output > b.output ? 1 : 0));
+  return { outputs, known, unknown: outputs.filter((o) => o.verdict !== "unchanged").map((o) => o.output) };
+}

package/src/plugin.ts

@@ -37,6 +37,7 @@
  *   takes a `<project>/<stack>` template, and `prEnvTeardown` removes the
  *   environment's `pr-<n>` stacks (`./review-stack.ts`).
  */
+import { pulumiCheckSteps } from "./check-step";
 import { pulumiCiSetup } from "./ci-setup";
 import { basename, isAbsolute, resolve } from "node:path";
 import type { InitTemplateSet, LexiconPlugin } from "@intentius/chant/lexicon";
@@ -95,6 +96,19 @@ export const pulumiPlugin: LexiconPlugin = {
     return reviewStackTeardown({ cwd: ctx.cwd });
   },
 
+  // #4633: pulumi install, each stack's config against the project's schema, and pulumi about --json, per pulumi member in chant's check stage.
+  checkSteps() {
+    return pulumiCheckSteps();
+  },
+
+  // #4634: preview tips (rename without aliases, a replace forced by a name, what may register at up) as a note section per member.
+  async prNoteDetail(input) {
+    if (input.stage !== "plan") return undefined;
+    const [{ pulumiTipsDetail }, { activeProductWords }] = await Promise.all([import("./preview-tips"), import("@intentius/chant/ci-product-words")]);
+    const words = activeProductWords();
+    return pulumiTipsDetail({ member: input.member, changeSet: input.changeSet, words: { product: words.product, noun: words.noun } });
+  },
+
   // A pulumi workspace member's reader project (#3179): its stack export from
   // the index store, else the checked-in one, never the program. See ./workspace-member.ts. `chant workspace
   // graph` writes `dir` absolute; a project that writes the namespace itself
@@ -122,6 +136,18 @@ export const pulumiPlugin: LexiconPlugin = {
     return { entities: read.entities, warnings: read.warnings };
   },
 
+  /**
+   * The stacks a change touched (#3183, INTENTIUS/plywood#22): a changed
+   * `Pulumi.<stack>.yaml` is that stack, any other file of a project is every
+   * stack with a config beside its `Pulumi.yaml`. Named as a `pulumi-up`
+   * step's deploy unit, so `chant components pr-plan` and `fan-out --base`
+   * select the components that update them. See ./changed-units.ts.
+   */
+  async changedUnits(ctx) {
+    const { pulumiChangedUnits } = await import("./changed-units");
+    return pulumiChangedUnits(ctx.projectRoot, ctx.changedFiles);
+  },
+
   graphMeta() {
     const report = lastMemberReport();
     return report ? { pulumiMember: report } : undefined;

package/src/preview-tips.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Preview tips (#4634) over the recorded preview stream
+ * (`testdata/pulumi-stream`, converted from the #4475 recording) and over
+ * copies of its steps edited in the test to show each pattern. No engine
+ * runs.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { withProductWords } from "@intentius/chant/ci-product-words";
+import { pulumiPreviewPart, type PulumiStep } from "./change-set";
+import { pulumiStreamPreview } from "./engine-events";
+import { pulumiPlugin } from "./plugin";
+import { nameStem, pulumiPreviewTips, pulumiTipsDetail } from "./preview-tips";
+
+const TESTDATA = join(import.meta.dirname, "testdata");
+const stream = readFileSync(join(TESTDATA, "pulumi-stream", "preview-stream.ndjson"), "utf8");
+const prior = JSON.parse(readFileSync(join(TESTDATA, "pulumi-preview", "stack-export.json"), "utf8")) as unknown;
+const recorded = (): PulumiStep[] => structuredClone(pulumiStreamPreview(stream).steps);
+
+const part = (steps: PulumiStep[]) => pulumiPreviewPart({ member: "app", preview: { steps }, prior });
+const doc = (steps: PulumiStep[]) => ({ entries: part(steps).entries });
+
+const BUCKET = "urn:pulumi:floci::corpus-aws-ts::aws:s3/bucket:Bucket::site-bucket";
+const ROLE = "urn:pulumi:floci::corpus-aws-ts::aws:iam/role:Role::app-role";
+
+/** The recorded steps with site-bucket deleted and site-bucket-v2 created in its place, as a rename with no alias previews. */
+function renamed(): PulumiStep[] {
+  const steps = recorded();
+  const at = steps.findIndex((s) => s.urn === BUCKET);
+  const bucket = steps[at]!;
+  const created: PulumiStep = { op: "create", urn: BUCKET.replace(/site-bucket$/, "site-bucket-v2"), newState: { ...bucket.newState!, urn: BUCKET.replace(/site-bucket$/, "site-bucket-v2") } };
+  steps[at] = { op: "delete", urn: BUCKET, oldState: bucket.oldState! };
+  steps.push(created);
+  return steps;
+}
+
+describe("the recorded preview", () => {
+  test("shows no tip: worker-2's delete has no create of its type and stem, and neither replace is forced by a name", () => {
+    const entries = part(recorded()).entries;
+    expect(entries.some((e) => e.action === "delete" && e.name === "worker-2")).toBe(true);
+    expect(pulumiPreviewTips(entries)).toEqual([]);
+    expect(pulumiTipsDetail({ member: "app", changeSet: { entries } })).toBeUndefined();
+  });
+});
+
+describe("rename-without-aliases", () => {
+  test("a delete and a create of one type and stem", () => {
+    expect(pulumiPreviewTips(doc(renamed()).entries)).toEqual([
+      { id: "rename-without-aliases", member: "app", address: BUCKET, type: "aws:s3/bucket:Bucket", name: "site-bucket", created: { address: BUCKET.replace(/site-bucket$/, "site-bucket-v2"), name: "site-bucket-v2" } },
+    ]);
+  });
+
+  test("the same name under a new parent", () => {
+    const steps = recorded();
+    const at = steps.findIndex((s) => s.urn === BUCKET);
+    const bucket = steps[at]!;
+    const moved = "urn:pulumi:floci::corpus-aws-ts::corpus:index:Site$aws:s3/bucket:Bucket::site-bucket";
+    steps[at] = { op: "delete", urn: BUCKET, oldState: bucket.oldState! };
+    steps.push({ op: "create", urn: moved, newState: { ...bucket.newState!, urn: moved } });
+    expect(pulumiPreviewTips(doc(steps).entries).map((t) => [t.id, t.created?.address])).toEqual([["rename-without-aliases", moved]]);
+  });
+
+  test("a different type, or a different stem, is no rename", () => {
+    const steps = recorded();
+    const bucket = steps.find((s) => s.urn === BUCKET)!;
+    const other = "urn:pulumi:floci::corpus-aws-ts::aws:s3/bucket:Bucket::logs";
+    steps.push({ op: "create", urn: other, newState: { ...bucket.newState!, urn: other } });
+    expect(pulumiPreviewTips(doc(steps).entries)).toEqual([]);
+    expect(nameStem("Site-Bucket_v2")).toBe("site");
+  });
+});
+
+describe("replace-on-name", () => {
+  test("a create-before-delete replace forced by name", () => {
+    const steps = recorded();
+    const at = steps.findIndex((s) => s.urn === ROLE);
+    const role = steps[at]!;
+    steps[at] = {
+      ...role,
+      op: "replace",
+      newState: { ...role.newState!, inputs: { ...(role.newState!.inputs as object), name: "app-role-2" } },
+      replaceReasons: ["name"],
+      diffReasons: ["name"],
+      detailedDiff: { name: { kind: "update-replace", inputDiff: true } },
+    };
+    const tips = pulumiPreviewTips(doc(steps).entries);
+    expect(tips).toEqual([expect.objectContaining({ id: "replace-on-name", name: "app-role", inputs: ["name"] })]);
+  });
+
+  test("a delete-before-replace already deletes first", () => {
+    const steps = recorded();
+    const at = steps.findIndex((s) => s.urn === ROLE);
+    const role = steps[at]!;
+    steps.splice(at, 1, { ...role, op: "delete-replaced", replaceReasons: ["name"] }, { ...role, op: "create-replacement", replaceReasons: ["name"] });
+    expect(pulumiPreviewTips(doc(steps).entries)).toEqual([]);
+  });
+});
+
+describe("unknown-in-apply", () => {
+  test("a component whose child waits on an unknown may register more at up", () => {
+    // The JSON recording: the stream omits a component's custom: false, which signal 1 of the change set reads.
+    const steps = structuredClone((JSON.parse(readFileSync(join(TESTDATA, "pulumi-preview", "preview.json"), "utf8")) as { steps: PulumiStep[] }).steps);
+    const child = steps.find((s) => s.urn?.endsWith("Site$aws:s3/bucket:Bucket::docs-assets"))!;
+    child.op = "update";
+    child.newState = { ...child.newState!, inputs: { ...(child.newState!.inputs as object), tags: "04da6b54-80e4-46f7-96ec-b56ff0331ba9" } };
+    child.diffReasons = ["tags"];
+    const tips = pulumiPreviewTips(doc(steps).entries);
+    expect(tips.map((t) => t.id)).toEqual(["unknown-in-apply"]);
+    expect(tips[0]!.address).toContain("corpus:index:Site$*::docs");
+  });
+});
+
+describe("the note", () => {
+  test("one row per tip with its id, and the product's tips command", () => {
+    const detail = pulumiTipsDetail({ member: "app", changeSet: doc(renamed()), words: { product: "plywood", noun: ["stack", "stacks"] } });
+    expect(detail).toEqual({
+      title: "Tips for stack `app` (1)",
+      lines: [
+        "| Tip | Resource | Preview |",
+        "|---|---|---|",
+        "| `rename-without-aliases` | `aws:s3/bucket:Bucket` `site-bucket` | deleted, and `site-bucket-v2` of the same type created, with no alias between them |",
+        "",
+        "`plywood tips rename-without-aliases` prints the fix.",
+      ],
+    });
+  });
+
+  test("the plugin renders it at plan, in the active product's words", async () => {
+    const changeSet = doc(renamed()) as never;
+    const detail = await withProductWords({ product: "plywood", noun: ["stack", "stacks"] }, async () => pulumiPlugin.prNoteDetail!({ member: "app", changeSet, stage: "plan" }));
+    expect(detail?.lines.at(-1)).toBe("`plywood tips rename-without-aliases` prints the fix.");
+    expect(await pulumiPlugin.prNoteDetail!({ member: "app", changeSet, stage: "apply" })).toBeUndefined();
+  });
+});

package/src/preview-tips.ts

@@ -0,0 +1,128 @@
+/**
+ * Preview tips from a Pulumi member's change set (#4634). A tip names a
+ * pattern in a preview that usually wants a fix before the update: the
+ * product holds each tip's words and fix (plywood's `src/tips.ts` and
+ * `plywood tips <id>`), and this module finds the pattern in the change set
+ * the preview became (`./change-set.ts`). The note shows each tip as a row
+ * with its id, through the lexicon's `prNoteDetail`.
+ *
+ * | id | found when |
+ * |---|---|
+ * | `rename-without-aliases` | the preview deletes a resource and creates one of the same type whose name has the same stem, or the same name under another parent |
+ * | `replace-on-name` | a replace that creates before it deletes, forced by a name input (`name`, `<x>Name`, `bucket`) |
+ * | `unknown-in-apply` | an entry the preview could not list (`mayAppear`): something registers inside an `apply()` |
+ *
+ * A rename with `aliases` is not a delete and a create: Pulumi follows the
+ * alias and the preview shows the resource under its new URN as `same` or
+ * `update`. So a delete and a create of one type and stem in one preview is
+ * the rename without them. The stem is the name up to its first `-`, `_`,
+ * `.`, `:` or `/`, lowercased, so `assets` and `assets-v2` pair, and so
+ * does `worker-2` with a new `worker-3`; each delete pairs with one create
+ * at most.
+ *
+ * Tips plywood lists that a change set cannot show are left out:
+ * `secret-in-plain-config` reads stack config, which no preview step holds,
+ * and `no-protect-on-data` reads `protect`, which the change set does not
+ * carry.
+ */
+import type { ChangeSetDocument, ChangeSetEntry } from "@intentius/chant/change-set";
+
+/** The tip ids this module finds, as plywood's tips page names them. */
+export const PULUMI_PREVIEW_TIP_IDS = ["rename-without-aliases", "replace-on-name", "unknown-in-apply"] as const;
+
+export type PulumiPreviewTipId = (typeof PULUMI_PREVIEW_TIP_IDS)[number];
+
+/** One tip found in a member's change set. */
+export interface PulumiPreviewTip {
+  id: PulumiPreviewTipId;
+  member: string;
+  /** The entry's address (a URN, or a may-appear address). */
+  address: string;
+  type: string;
+  name?: string;
+  /** For a rename: the created resource's address and name. */
+  created?: { address: string; name?: string };
+  /** For a replace: the name inputs that force it. */
+  inputs?: string[];
+}
+
+/** The stem a rename keeps: the name up to its first separator, lowercased. */
+export function nameStem(name: string): string {
+  return name.toLowerCase().split(/[-_.:/]/)[0] ?? "";
+}
+
+/** A name input: `name`, `<x>Name`, `<x>_name`, or an S3 bucket's `bucket`. */
+const NAME_INPUT = /^(name|bucket|[a-z][A-Za-z0-9]*Name|[a-z0-9_]+_name)$/;
+
+/** The tips in `entries`, in order: renames, then replaces, then what may register at up. Only pulumi entries are read. */
+export function pulumiPreviewTips(entries: readonly ChangeSetEntry[]): PulumiPreviewTip[] {
+  const mine = entries.filter((e) => e.lexicon === "pulumi");
+  const tips: PulumiPreviewTip[] = [];
+  const base = (e: ChangeSetEntry) => ({ member: e.member, address: e.address, type: e.type, ...(e.name !== undefined ? { name: e.name } : {}) });
+
+  // rename-without-aliases
+  const creates = mine.filter((e) => e.action === "create" && e.mayAppear !== true && e.name !== undefined);
+  const taken = new Set<string>();
+  for (const del of mine) {
+    if (del.action !== "delete" || del.mayAppear === true || del.name === undefined) continue;
+    const stem = nameStem(del.name);
+    if (!stem) continue;
+    const match = creates.find((c) => !taken.has(c.address) && c.member === del.member && c.type === del.type && c.address !== del.address && nameStem(c.name!) === stem);
+    if (!match) continue;
+    taken.add(match.address);
+    tips.push({ id: "rename-without-aliases", ...base(del), created: { address: match.address, ...(match.name !== undefined ? { name: match.name } : {}) } });
+  }
+
+  // replace-on-name
+  for (const e of mine) {
+    if (e.action !== "replace" || e.disruption === "destroy") continue;
+    const inputs = e.attributes.filter((a) => a.forcesReplacement === true && NAME_INPUT.test(a.path)).map((a) => a.path);
+    if (inputs.length > 0) tips.push({ id: "replace-on-name", ...base(e), inputs });
+  }
+
+  // unknown-in-apply
+  for (const e of mine) {
+    if (e.mayAppear === true) tips.push({ id: "unknown-in-apply", ...base(e) });
+  }
+  return tips;
+}
+
+const code = (s: string): string => "`" + s.replace(/`/g, "'") + "`";
+
+/** What the row says the preview showed. */
+function seen(t: PulumiPreviewTip): string {
+  switch (t.id) {
+    case "rename-without-aliases":
+      return `deleted, and ${code(t.created?.name ?? t.created?.address ?? "?")} of the same type created, with no alias between them`;
+    case "replace-on-name":
+      return `replaced because ${t.inputs!.map(code).join(", ")} changed, creating the new one before deleting the old`;
+    case "unknown-in-apply":
+      return "may register at up: the preview could not list it";
+  }
+}
+
+/** The words the detail section reads: the product's name and its noun. */
+export interface PulumiTipWords {
+  product: string;
+  noun: [string, string];
+}
+
+/**
+ * The note's detail section for one member's tips (`prNoteDetail`), or
+ * undefined when it has none. One row per tip, with its id first. A product
+ * other than chant gets a closing line naming `<product> tips <id>`, the
+ * command its words give the fix with.
+ */
+export function pulumiTipsDetail(input: { member: string; changeSet: Pick<ChangeSetDocument, "entries">; words?: PulumiTipWords }): { title: string; lines: string[] } | undefined {
+  const tips = pulumiPreviewTips(input.changeSet.entries.filter((e) => e.member === input.member));
+  if (tips.length === 0) return undefined;
+  const words = input.words ?? { product: "chant", noun: ["member", "members"] };
+  const lines = ["| Tip | Resource | Preview |", "|---|---|---|"];
+  for (const t of tips) lines.push(`| ${code(t.id)} | ${code(t.type)} ${code(t.name ?? t.address)} | ${seen(t)} |`);
+  if (words.product !== "chant") {
+    const ids = [...new Set(tips.map((t) => t.id))];
+    lines.push("", `${ids.map((id) => code(`${words.product} tips ${id}`)).join(", ")} ${ids.length === 1 ? "prints the fix" : "print the fixes"}.`);
+  }
+  const noun = words.noun[0];
+  return { title: `Tips for ${noun} ${code(input.member)} (${tips.length})`, lines };
+}

package/src/pulumi-up.test.ts

@@ -299,6 +299,63 @@ describe("releaseInputs (#4542)", () => {
   });
 });
 
+describe("the step's backend (plywood#22)", () => {
+  const store = "plunge+s3://plywood-tutorial-plunge?region=us-east-1&endpoint=http://floci:4566&s3ForcePathStyle=true";
+
+  test("plunge's preview, up and output read each get it as PULUMI_BACKEND_URL, over the job's", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: { PULUMI_BACKEND_URL: "file:///tmp/plywood-tutorial-backend" }, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ engine: "plunge", backend: store }));
+    await cap.run({ ...ctx, plans: { [member]: planned.artifact as PulumiUpArtifact } }, step({ engine: "plunge", backend: store }));
+    expect(plunge.calls.map((c) => c.args[0])).toEqual(["preview", "up", "stack"]);
+    for (const c of plunge.calls) expect(c.env?.PULUMI_BACKEND_URL).toBe(store);
+    // The preview keeps its streaming flag beside the backend.
+    expect(plunge.calls[0].env).toEqual({ [PULUMI_STREAMING_PREVIEW_ENV]: "true", PULUMI_BACKEND_URL: store });
+  });
+
+  test("stock Pulumi's preview, up and output read get it too, and outputs() reads through it", async () => {
+    const pulumi = engine();
+    const s3 = "s3://plywood-tutorial-state?region=us-east-1&endpoint=http://floci:4566&use_path_style=true";
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ engine: "pulumi", backend: s3 }));
+    await cap.run({ ...ctx, plans: { [member]: planned.artifact as PulumiUpArtifact } }, step({ engine: "pulumi", backend: s3 }));
+    await cap.outputs!(ctx, step({ engine: "pulumi", backend: s3 }));
+    expect(pulumi.calls.length).toBeGreaterThanOrEqual(4);
+    for (const c of pulumi.calls) expect(c.env?.PULUMI_BACKEND_URL).toBe(s3);
+  });
+
+  test("a plunge+ backend picks plunge where the job's PULUMI_BACKEND_URL would have picked stock Pulumi", async () => {
+    const plunge = engine();
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, plunge: plunge.run, env: { PULUMI_BACKEND_URL: "file:///tmp/b" }, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ backend: store }));
+    expect((planned.artifact as PulumiUpArtifact).engine).toBe("plunge");
+    expect(pulumi.calls).toHaveLength(0);
+    expect(cap.defaultLockGrain!(step({ backend: store }))).toBe("resource");
+  });
+
+  test("the ledger lock (ruling for ci-products 2026-10-28): a stack's target row is its stack row, from Pulumi.yaml's name", () => {
+    const cap = createPulumiUpCapability({ env: {}, tmp: tmp(), snapshots: null });
+    expect(cap.targetLockRow!(step())).toEqual({ key: "stack corpus-aws-ts/floci", target: member, address: "corpus-aws-ts/floci" });
+    // A plunge stack on the resource grain still leases URN rows; the stack row it may also take meets this one.
+    expect(cap.targetLockRow!(step({ stack: "prod-us" }))).toMatchObject({ key: "stack corpus-aws-ts/prod-us" });
+  });
+
+  test("without it nothing changes: no PULUMI_BACKEND_URL is added", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: {}, tmp: tmp(), snapshots: null });
+    await cap.plan!(ctx, step({ engine: "plunge" }));
+    expect(plunge.calls[0].env).toEqual({ [PULUMI_STREAMING_PREVIEW_ENV]: "true" });
+  });
+
+  test("an empty backend is refused before anything runs", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: {}, tmp: tmp(), snapshots: null });
+    await expect(cap.plan!(ctx, step({ engine: "plunge", backend: " " }))).rejects.toThrow(/"backend" is the stack's backend URL/);
+    expect(plunge.calls).toHaveLength(0);
+  });
+});
+
 describe("a step pinned to its engine release (#4592)", () => {
   test("engineVersion runs the versioned binary, through the same argv checks", async () => {
     const pinned = engine();
@@ -423,6 +480,8 @@ describe("CrossGuard packs read at base (#4613)", () => {
     const stack = join(top, "stack");
     mkdirSync(join(stack, "guard"), { recursive: true });
     for (const f of ["Pulumi.yaml", "stack-export.json"]) copyFileSync(join(dir, f), join(stack, f));
+    // An installed checkout, so the step runs no install before the preview (plywood#22).
+    mkdirSync(join(stack, "node_modules"));
     writeFileSync(join(stack, "guard", "index.ts"), "// no-public-bucket: mandatory\n");
     git(top, "add", ".");
     git(top, "commit", "-q", "-m", "base");
@@ -468,3 +527,44 @@ describe("CrossGuard packs read at base (#4613)", () => {
     expect(pulumi.calls).toHaveLength(0);
   });
 });
+
+describe("an in-place checkout (plywood#22)", () => {
+  /** A checkout of the corpus program: Pulumi.yaml, package.json and, unless left out, a lockfile; no node_modules. */
+  function checkout(lockfile = true): string {
+    const stack = tmp();
+    for (const f of ["Pulumi.yaml", "stack-export.json"]) copyFileSync(join(dir, f), join(stack, f));
+    writeFileSync(join(stack, "package.json"), "{}\n");
+    if (lockfile) writeFileSync(join(stack, "package-lock.json"), "{}\n");
+    return stack;
+  }
+
+  test("a Node checkout with a lockfile and no node_modules gets one install, with the step's backend, before the first preview", async () => {
+    const stack = checkout();
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ dir: stack, engine: "pulumi", backend: "s3://shop-state" }));
+    expect(pulumi.calls[0]).toMatchObject({ args: ["install"], cwd: stack, env: { PULUMI_BACKEND_URL: "s3://shop-state" } });
+    expect(pulumi.calls[1]!.args[0]).toBe("preview");
+
+    await cap.run({ ...ctx, plans: { [planned.member]: planned.artifact as PulumiUpArtifact } }, step({ dir: stack, engine: "pulumi", backend: "s3://shop-state" }));
+    expect(pulumi.calls.filter((c) => c.args[0] === "install")).toHaveLength(1);
+    expect(pulumi.calls.some((c) => c.args[0] === "up")).toBe(true);
+  });
+
+  test("a Node checkout with no lockfile is refused by name before the engine runs", async () => {
+    const stack = checkout(false);
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    await expect(cap.plan!(ctx, step({ dir: stack, engine: "pulumi" }))).rejects.toThrow(/no lockfile .* beside its package.json/);
+    expect(pulumi.calls).toHaveLength(0);
+  });
+
+  test("an installed checkout runs no install", async () => {
+    const stack = checkout();
+    mkdirSync(join(stack, "node_modules"));
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    await cap.plan!(ctx, step({ dir: stack, engine: "pulumi" }));
+    expect(pulumi.calls.map((c) => c.args[0])).not.toContain("install");
+  });
+});