@intentius/chant-lexicon-pulumi 0.124.55 → 0.124.56

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

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

@@ -167,6 +167,7 @@ import { pulumiExitOf } from "./exit-codes";
 import { pulumiMemberEngine, type PulumiMemberEngine, type PulumiMemberEngineSource } from "./member-engine";
 import { ciEngineDir, ciRelease, CI_ENGINE_ROOT } from "./ci-setup";
 import { pulumiMemberPlannedOutputs } from "./member-outputs";
+import type { PulumiOutputChange } from "./planned-output-changes";
 import { pulumiPlanShape, pulumiShapeDifferences } from "./plan-shape";
 import { pulumiLockRows } from "./lock-rows";
 import { pulumiTraceFacts } from "./trace-facts";
@@ -300,6 +301,13 @@ export interface PulumiUpArtifact {
    * outside reference stale, current or unknown.
    */
   stackReferences?: { read: string[]; outside: { name: string; why: string }[]; lastUpdate?: string };
+  /**
+   * Each stack output's verdict from the preview (#4635,
+   * `./planned-output-changes.ts`): `changing` and `untraced` ones are
+   * unknown to the stacks that read them, `unchanged` ones keep the
+   * export's value. Absent when the preview planned nothing to apply.
+   */
+  plannedOutputs?: PulumiOutputChange[];
 }
 
 /** The CrossGuard packs a plan read at base (#4613). */
@@ -619,7 +627,10 @@ async function previewStack(
     stack: input.stack,
     ...(files.planFile ? { savePlan: files.planFile } : {}),
     ...(files.configFile ? { configFile: files.configFile } : {}),
+    // #4627: --refresh and --target-dependents pass to the preview as they came.
+    ...(ctx.refresh ? { refresh: true } : {}),
     ...(targets ? { targets } : {}),
+    ...(targets && ctx.targetDependents ? { targetDependents: true } : {}),
     ...(packs.length ? { policyPacks: packs } : {}),
   });
   let stdout: string;
@@ -720,7 +731,12 @@ async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts:
   }
   const planDigest = read.part.member.planDigest!;
   const references = stackReferencesOf(read.prior, input);
-  const planned = pulumiMemberPlannedOutputs(r.member, { part: read.part, preview: read.preview, ...(read.prior !== undefined ? { exported: read.prior } : {}) });
+  const planned = pulumiMemberPlannedOutputs(r.member, {
+    part: read.part,
+    preview: read.preview,
+    ...(read.prior !== undefined ? { exported: read.prior } : {}),
+    ...(ctx.targets?.length ? { targeted: true } : {}),
+  });
   const artifact: PulumiUpArtifact = {
     kind: "pulumi-up",
     member: r.member,
@@ -736,6 +752,7 @@ async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts:
     policy: read.policy,
     ...(packs.read ? { policyPacks: packs.read } : {}),
     ...(references ? { stackReferences: references } : {}),
+    ...(planned.outputChanges ? { plannedOutputs: planned.outputChanges } : {}),
   };
   return {
     member: r.member,
@@ -892,6 +909,7 @@ async function runStack(ctx: DeployContext, original: PulumiUpStepInput, opts: P
   const tail = {
     ...(configFile ? { configFile } : {}),
     ...(targets ? { targets } : {}),
+    ...(targets && ctx.targetDependents ? { targetDependents: true } : {}),
     ...(policyPacks?.length ? { policyPacks } : {}),
   };
 
@@ -914,7 +932,8 @@ async function runStack(ctx: DeployContext, original: PulumiUpStepInput, opts: P
         if (differences.length > 0) throw new PlanShapeMovedError(r.member, differences);
       }
       try {
-        ({ stdout } = await runApplyPulumi(runnersFor(r, opts).pulumi, pulumiUpArgs({ stack: input.stack, ...tail }), r.dir));
+        // #4627: stock up plans again, so it refreshes as its preview did; plunge applies the saved plan, whose preview refreshed.
+        ({ stdout } = await runApplyPulumi(runnersFor(r, opts).pulumi, pulumiUpArgs({ stack: input.stack, ...tail, ...(ctx.refresh ? { refresh: true } : {}) }), r.dir));
       } catch (err) {
         throw upFailure(r, err, approved.policy);
       }
@@ -989,6 +1008,8 @@ export function createPulumiUpCapability(opts: PulumiUpOptions = {}): Capability
     rollbackPolicy: "needs-opt-out",
     // Each target passes as `--target <urn>` to the preview and to `up`.
     targets: "accept",
+    // #4627: `--refresh` and `--target-dependents` pass to the preview, and to `pulumi up`; the digest binds them.
+    planFlags: { refresh: "accept", targetDependents: "accept" },
     plan: (ctx, input) => planStack(ctx, input, opts),
     run: (ctx, input) => runStack(ctx, input, opts),
     // The outputs standing now, for a dependent planned before this stack applies.

package/src/run-plan-flags.test.ts

@@ -0,0 +1,53 @@
+/**
+ * `--refresh` and `--target-dependents` through the pulumi lexicon's
+ * allowlists (#4627): both in the preview and in stock `pulumi up`, in the
+ * tail's order, `--target-dependents` only after a `--target`, and no
+ * `--refresh` on plunge's `up --plan`, which applies a saved plan whose
+ * preview refreshed. Written for the ci-products post-merge pass.
+ */
+import { describe, expect, test } from "vitest";
+import { plungeUpArgs, pulumiUpArgs, pulumiUpPreviewArgs, runAllowedPlunge, runAllowedPulumi, runApplyPlunge, runApplyPulumi, type PulumiRunner } from "./run";
+import { createPulumiUpCapability } from "./pulumi-up";
+
+function fake(): { run: PulumiRunner; calls: string[][] } {
+  const calls: string[][] = [];
+  return { run: async (args) => (calls.push(args), { stdout: "" }), calls };
+}
+
+describe("--refresh and --target-dependents (#4627)", () => {
+  test("the preview carries them in the tail's order", async () => {
+    const args = pulumiUpPreviewArgs({ stack: "dev", refresh: true, targets: ["urn:a"], targetDependents: true });
+    expect(args).toEqual(["preview", "--json", "--show-sames", "--stack", "dev", "--refresh", "--target", "urn:a", "--target-dependents"]);
+    const { run, calls } = fake();
+    await runAllowedPulumi(run, args, "/tmp");
+    await runAllowedPlunge(run, args, "/tmp");
+    expect(calls).toHaveLength(2);
+  });
+
+  test("--target-dependents is dropped without a target", () => {
+    expect(pulumiUpPreviewArgs({ stack: "dev", targetDependents: true })).not.toContain("--target-dependents");
+  });
+
+  test("stock up takes both; plunge up --plan takes --target-dependents and no --refresh", async () => {
+    const { run, calls } = fake();
+    await runApplyPulumi(run, pulumiUpArgs({ stack: "dev", refresh: true, targets: ["urn:a"], targetDependents: true }), "/tmp");
+    await runApplyPlunge(run, plungeUpArgs({ plan: "/tmp/p.json", stack: "dev", targets: ["urn:a"], targetDependents: true }), "/tmp");
+    expect(calls).toEqual([
+      ["up", "--yes", "--json", "--stack", "dev", "--refresh", "--target", "urn:a", "--target-dependents"],
+      ["up", "--plan", "/tmp/p.json", "--yes", "--json", "--stack", "dev", "--target", "urn:a", "--target-dependents"],
+    ]);
+    await expect(runApplyPlunge(run, ["up", "--plan", "/tmp/p.json", "--yes", "--json", "--stack", "dev", "--refresh"], "/tmp")).rejects.toThrow(/applies a plunge stack only as/);
+  });
+
+  test("out of order, or --target-dependents with no target, is refused", async () => {
+    const { run, calls } = fake();
+    for (const tail of [["--target-dependents"], ["--target", "urn:a", "--refresh"], ["--target-dependents", "--target", "urn:a"], ["--refresh", "--refresh"]]) {
+      await expect(runApplyPulumi(run, ["up", "--yes", "--json", "--stack", "dev", ...tail], "/tmp"), tail.join(" ")).rejects.toThrow(/applies a Pulumi stack only as/);
+    }
+    expect(calls).toEqual([]);
+  });
+
+  test("the capability says it takes both", () => {
+    expect(createPulumiUpCapability().planFlags).toEqual({ refresh: "accept", targetDependents: "accept" });
+  });
+});