@intentius/chant-lexicon-pulumi 0.124.55 → 0.124.56

package/src/check-step.test.ts

@@ -0,0 +1,191 @@
+/**
+ * The pulumi check steps (#4633): install, stack config against the
+ * project's schema, and about, with a fake runner, so no binary runs and no
+ * backend is read or written.
+ */
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { runCheckStage } from "@intentius/chant/components/check-steps";
+import { listedStacks, pulumiAboutDetail, pulumiCheckSteps, pulumiMemberCheck, pulumiProjectSchema, pulumiStackConfigProblems } from "./check-step";
+import { pulumiPlugin } from "./plugin";
+import { allowedCheck, runCheckPulumi, type PulumiRunner } from "./run";
+
+const PROJECT = `name: shop
+runtime: nodejs
+config:
+  aws:region: us-east-1
+  replicas:
+    type: integer
+  size:
+    type: string
+    default: small
+  dbPassword:
+    type: string
+    secret: true
+  zones:
+    type: array
+    items:
+      type: string
+`;
+
+const ABOUT = JSON.stringify({
+  cli: { version: "3.140.0" },
+  plugins: [{ name: "aws", version: "6.60.0" }, { name: "nodejs", version: "unknown" }],
+  backend: { name: "laptop", url: "file:///tmp/state", user: "ci" },
+});
+
+function member(files: Record<string, string>, fields: Record<string, unknown> | null = null) {
+  const dir = mkdtempSync(join(tmpdir(), "chant-pulumi-check-"));
+  for (const [name, text] of Object.entries(files)) {
+    mkdirSync(join(dir, name, ".."), { recursive: true });
+    writeFileSync(join(dir, name), text);
+  }
+  return { name: "shop", dir, kind: "pulumi", fields };
+}
+
+function fake(answers: Record<string, { stdout?: string; fail?: { code?: number | string; stderr?: string; stdout?: string } }>) {
+  const calls: Array<{ engine: string; args: string[]; env?: Record<string, string> }> = [];
+  const runner = (engine: string, env: Record<string, string>): PulumiRunner => async (args) => {
+    calls.push({ engine, args, env });
+    const a = answers[args.join(" ")] ?? { stdout: "" };
+    if (a.fail) throw Object.assign(new Error(`${engine} ${args.join(" ")} failed`), a.fail);
+    return { stdout: a.stdout ?? "" };
+  };
+  return { calls, runner };
+}
+
+const ctx = { env: { PATH: "/bin" }, log: () => {} };
+
+describe("the check argv (#4633)", () => {
+  test("install and about --json, optionally with a stack, and nothing else", () => {
+    expect(allowedCheck(["install"])).toBe(true);
+    expect(allowedCheck(["about", "--json"])).toBe(true);
+    expect(allowedCheck(["about", "--json", "--stack", "dev"])).toBe(true);
+    expect(allowedCheck(["install", "--reinstall"])).toBe(false);
+    expect(allowedCheck(["about"])).toBe(false);
+    expect(allowedCheck(["about", "--json", "--stack", "--yes"])).toBe(false);
+    expect(allowedCheck(["up", "--yes"])).toBe(false);
+  });
+
+  test("runCheckPulumi refuses an argv off the list before the runner sees it", async () => {
+    let ran = false;
+    const run: PulumiRunner = async () => {
+      ran = true;
+      return { stdout: "" };
+    };
+    await expect(runCheckPulumi(run, ["up", "--yes"], "/tmp")).rejects.toThrow(/check stage runs only/);
+    expect(ran).toBe(false);
+  });
+});
+
+describe("stack config against the project's schema", () => {
+  const schema = pulumiProjectSchema({ name: "shop", config: { "aws:region": "us-east-1", replicas: { type: "integer" }, size: { type: "string", default: "small" }, dbPassword: { type: "string", secret: true }, zones: { type: "array", items: { type: "string" } } } });
+
+  test("reads the keys in full form", () => {
+    expect(schema.keys.map((k) => k.key)).toEqual(["aws:region", "shop:replicas", "shop:size", "shop:dbPassword", "shop:zones"]);
+    expect(schema.stackConfigDir).toBe(".");
+  });
+
+  test("a stack that sets every required key with the right types passes", () => {
+    expect(pulumiStackConfigProblems(schema, "dev", { config: { "shop:replicas": "3", "shop:dbPassword": { secure: "AAAB" }, "shop:zones": ["a", "b"] } })).toEqual([]);
+  });
+
+  test("a missing key with no default, a wrong type and a plain-text secret are each named", () => {
+    const problems = pulumiStackConfigProblems(schema, "prod", { config: { "shop:size": 3, "shop:dbPassword": "hunter2", "shop:zones": ["a", ["b"]] } });
+    expect(problems).toEqual([
+      "stack prod is missing the configuration value shop:replicas (type integer, no default)",
+      "stack prod sets shop:dbPassword in plain text, and the project declares it secret; set it with pulumi config set --secret",
+      'stack prod sets shop:zones[1] to ["b"], which is not of type string',
+    ]);
+    expect(pulumiStackConfigProblems(schema, "qa", { config: { replicas: "three" } })[0]).toBe('stack qa sets shop:replicas to "three", which is not of type integer');
+  });
+
+  test("the listed stacks are the stack files", () => {
+    const m = member({ "Pulumi.yaml": PROJECT, "Pulumi.dev.yaml": "config: {}\n", "Pulumi.prod.yml": "config: {}\n" });
+    expect(listedStacks(m.dir)).toEqual(["dev", "prod"]);
+  });
+});
+
+describe("pulumi about --json", () => {
+  test("reads the engine, plugins and backend", () => {
+    expect(pulumiAboutDetail("pulumi", ABOUT)).toEqual({
+      engine: "pulumi",
+      version: "3.140.0",
+      plugins: [{ name: "aws", version: "6.60.0" }, { name: "nodejs", version: "unknown" }],
+      backend: { name: "laptop", url: "file:///tmp/state", user: "ci" },
+    });
+    expect(pulumiAboutDetail("pulumi", "not json")).toBeUndefined();
+  });
+});
+
+describe("a member's steps", () => {
+  test("install, each stack's config and about pass in order, with the check job's environment", async () => {
+    const m = member({ "Pulumi.yaml": PROJECT, "Pulumi.dev.yaml": "config:\n  shop:replicas: \"2\"\n  shop:dbPassword:\n    secure: AAAB\n  shop:zones: [a, b]\n" });
+    const { calls, runner } = fake({ "about --json": { stdout: ABOUT } });
+    const out = await pulumiMemberCheck(m, ctx, { runner });
+    expect(out.map((o) => [o.step, o.stack ?? "", o.outcome])).toEqual([
+      ["pulumi-install", "", "passed"],
+      ["stack-config", "dev", "passed"],
+      ["pulumi-about", "", "passed"],
+    ]);
+    expect(calls.map((c) => c.args.join(" "))).toEqual(["install", "about --json"]);
+    expect(calls.every((c) => c.engine === "pulumi" && c.env?.PATH === "/bin")).toBe(true);
+  });
+
+  test("a member on plunge runs plunge, and its declared stack goes to about", async () => {
+    const m = member({ "Pulumi.yaml": PROJECT }, { engine: "plunge", stack: "dev" });
+    const { calls, runner } = fake({ "about --json --stack dev": { stdout: ABOUT } });
+    const out = await pulumiMemberCheck(m, ctx, { runner });
+    expect(calls.map((c) => `${c.engine} ${c.args.join(" ")}`)).toEqual(["plunge install", "plunge about --json --stack dev"]);
+    // dev has no stack file, and replicas has no default.
+    expect(out.find((o) => o.step === "stack-config")).toMatchObject({ stack: "dev", outcome: "failed", reason: expect.stringContaining("member shop: stack dev is missing the configuration value shop:replicas") });
+  });
+
+  test("a failed install names the member, and about does not run", async () => {
+    const m = member({ "Pulumi.yaml": PROJECT, "Pulumi.dev.yaml": "config:\n  shop:replicas: 1\n  shop:dbPassword:\n    secure: x\n" });
+    const { calls, runner } = fake({ install: { fail: { code: 255, stderr: "error: npm install failed\n" } } });
+    const out = await pulumiMemberCheck(m, ctx, { runner });
+    expect(out[0]).toMatchObject({ step: "pulumi-install", outcome: "failed", exit: 255, reason: "pulumi install failed for member shop: error: npm install failed" });
+    expect(out.at(-1)).toMatchObject({ step: "pulumi-about", outcome: "skipped" });
+    expect(calls.map((c) => c.args.join(" "))).toEqual(["install"]);
+  });
+
+  test("about that exits non-zero but prints its JSON still reports", async () => {
+    const m = member({ "Pulumi.yaml": "name: shop\nruntime: nodejs\n" });
+    const { runner } = fake({ "about --json": { fail: { code: 1, stdout: ABOUT, stderr: "error: not logged in" } } });
+    const out = await pulumiMemberCheck(m, ctx, { runner });
+    expect(out.find((o) => o.step === "pulumi-about")).toMatchObject({ outcome: "passed", exit: 1, detail: { version: "3.140.0" } });
+    expect(out.find((o) => o.step === "stack-config")).toMatchObject({ outcome: "skipped" });
+  });
+
+  test("a member with no Pulumi.yaml fails, naming it", async () => {
+    const m = member({ "README.md": "x" });
+    const out = await pulumiMemberCheck(m, ctx, { runner: fake({}).runner });
+    expect(out).toEqual([expect.objectContaining({ step: "pulumi-install", outcome: "failed", reason: expect.stringContaining("has no Pulumi.yaml") })]);
+  });
+});
+
+describe("in the check stage", () => {
+  test("the plugin gives the steps for the pulumi kind", () => {
+    expect(pulumiPlugin.checkSteps?.()).toMatchObject({ lexicon: "pulumi", kinds: ["pulumi"] });
+  });
+
+  test("a failed step fails the stage after the hooks, naming member and stack", async () => {
+    const m = member({ "Pulumi.yaml": PROJECT, "Pulumi.prod.yaml": "config: {}\n" });
+    const cwd = mkdtempSync(join(tmpdir(), "chant-pulumi-stage-"));
+    const report = await runCheckStage({
+      base: "abc123",
+      cwd,
+      read: { base: "abc123", hooks: [] },
+      members: [m],
+      adapters: [pulumiCheckSteps({ runner: fake({ "about --json": { stdout: ABOUT } }).runner })],
+      env: {},
+      log: () => {},
+    });
+    expect(report.status).toBe("failed");
+    expect(report.failed).toContain("member shop: stack prod is missing the configuration value shop:replicas");
+    expect(report.steps?.map((s) => s.step)).toEqual(["pulumi-install", "stack-config", "pulumi-about"]);
+  });
+});

package/src/check-step.ts

@@ -0,0 +1,316 @@
+/**
+ * The pulumi lexicon's steps in chant's check stage (#4633). `chant ci
+ * check` runs them after the `ci.hooks.check` hooks, for each workspace
+ * member of kind `pulumi` (`LexiconPlugin.checkSteps`,
+ * `@intentius/chant/components/check-steps`), so a product's check
+ * (`plywood check`) gets them through chant with nothing of its own:
+ *
+ * - `pulumi-install`: `pulumi install` (`plunge install` for a member on
+ *   plunge, `./member-engine.ts`) in the member's directory, which fetches
+ *   the program's dependencies and plugins the way `Pulumi.yaml` says;
+ * - `stack-config`: each stack's `Pulumi.<stack>.yaml` checked against the
+ *   project's config schema in `Pulumi.yaml`, with no command run (a key
+ *   with a type and no default must be set, a value must read as its type,
+ *   and a `secret: true` key must be encrypted). The stacks are the ones the
+ *   project lists by their files, plus the member's declared stack;
+ * - `pulumi-about`: `pulumi about --json`, which reports the engine, its
+ *   plugins and the backend for the report.
+ *
+ * The argv go through `runCheckPulumi` (`./run.ts`), which refuses any
+ * other. The environment is the check job's ({@link CheckStepsContext.env}):
+ * no forge token, no OIDC request variables, no cloud credential, so neither
+ * command can write a stack. A failure names the member and stack, and the
+ * check exits with chant's `failed` code.
+ *
+ * The runner is injectable, so the tests run no binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { CheckStageMember, CheckStepOutcome, CheckStepsAdapter, CheckStepsContext } from "@intentius/chant/components/check-steps";
+import { parseYAML } from "@intentius/chant/yaml";
+import { pulumiMemberEngine, type PulumiMemberEngine } from "./member-engine";
+import { engineEnv, pulumiRunFailure, runCheckPulumi, type PulumiRunner } from "./run";
+
+const execFileAsync = promisify(execFile);
+
+/** The lexicon name the report carries. */
+const LEXICON = "pulumi";
+
+/** A runner for `bin` with exactly `env` (the check job's), never the process's whole environment. */
+export function checkRunner(bin: PulumiMemberEngine, env: Record<string, string>): PulumiRunner {
+  return (args, opts) => execFileAsync(bin, args, { cwd: opts.cwd, maxBuffer: 64 * 1024 * 1024, env: engineEnv({ ...env, ...opts.env }) });
+}
+
+// ── Stack config against the project's schema ───────────────────────
+
+/** One key the project declares in `Pulumi.yaml`'s `config:`. */
+export interface PulumiConfigKey {
+  /** The full key, `<project>:<name>` for a project key. */
+  key: string;
+  type?: string;
+  items?: { type?: string };
+  secret: boolean;
+  /** Whether it has a `default` or a project-level `value`. */
+  hasDefault: boolean;
+}
+
+/** The project's config schema: its name, the keys it declares, and where its stack files are. */
+export interface PulumiProjectSchema {
+  project: string;
+  keys: PulumiConfigKey[];
+  /** The directory the stack files are in, relative to the project (`stackConfigDir`), or "." */
+  stackConfigDir: string;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The key in its full form: a bare name belongs to the project. */
+function fullKey(project: string, key: string): string {
+  return key.includes(":") ? key : `${project}:${key}`;
+}
+
+/** Read `Pulumi.yaml`'s schema from its parsed document. A short-form entry (`key: value`) is a value with no type. */
+export function pulumiProjectSchema(doc: unknown): PulumiProjectSchema {
+  const d = isRecord(doc) ? doc : {};
+  const project = typeof d.name === "string" ? d.name : "";
+  const config = isRecord(d.config) ? d.config : {};
+  const keys: PulumiConfigKey[] = [];
+  for (const [name, entry] of Object.entries(config)) {
+    const key = fullKey(project, name);
+    const schema = isRecord(entry) && ("type" in entry || "default" in entry || "value" in entry || "secret" in entry || "description" in entry || "items" in entry);
+    if (!schema) {
+      keys.push({ key, secret: false, hasDefault: true });
+      continue;
+    }
+    const e = entry as Record<string, unknown>;
+    keys.push({
+      key,
+      ...(typeof e.type === "string" ? { type: e.type } : {}),
+      ...(isRecord(e.items) && typeof e.items.type === "string" ? { items: { type: e.items.type } } : {}),
+      secret: e.secret === true,
+      hasDefault: "default" in e || "value" in e,
+    });
+  }
+  return { project, keys, stackConfigDir: typeof d.stackConfigDir === "string" && d.stackConfigDir.length > 0 ? d.stackConfigDir : "." };
+}
+
+const isSecure = (v: unknown): boolean => isRecord(v) && typeof v.secure === "string";
+
+/** Whether a scalar stack value reads as `type`. Values are strings once Pulumi reads them, so `"3"` is an integer. */
+function readsAs(type: string, value: unknown): boolean {
+  switch (type) {
+    case "string":
+      return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    case "integer":
+      return (typeof value === "number" && Number.isInteger(value)) || (typeof value === "string" && /^-?[0-9]+$/.test(value.trim()));
+    case "boolean":
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array":
+      return Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
+/**
+ * What is wrong with one stack's config (`config:` of its
+ * `Pulumi.<stack>.yaml`, parsed) against the project's schema, as lines
+ * naming the stack and key. Empty when it passes. Keys of other namespaces
+ * (a provider's `aws:region`) are not checked: the project declares no type
+ * for them.
+ */
+export function pulumiStackConfigProblems(schema: PulumiProjectSchema, stack: string, stackDoc: unknown): string[] {
+  const raw = isRecord(stackDoc) && isRecord(stackDoc.config) ? stackDoc.config : {};
+  const values = new Map<string, unknown>();
+  for (const [k, v] of Object.entries(raw)) values.set(fullKey(schema.project, k), v);
+  const problems: string[] = [];
+  for (const k of schema.keys) {
+    if (!k.type && !k.secret) continue;
+    if (!values.has(k.key)) {
+      if (k.type && !k.hasDefault) problems.push(`stack ${stack} is missing the configuration value ${k.key} (type ${k.type}, no default)`);
+      continue;
+    }
+    const value = values.get(k.key);
+    if (k.secret && !isSecure(value)) {
+      problems.push(`stack ${stack} sets ${k.key} in plain text, and the project declares it secret; set it with pulumi config set --secret`);
+      continue;
+    }
+    if (isSecure(value) || !k.type) continue;
+    if (!readsAs(k.type, value)) {
+      problems.push(`stack ${stack} sets ${k.key} to ${JSON.stringify(value)}, which is not of type ${k.type}`);
+      continue;
+    }
+    if (k.type === "array" && k.items?.type && Array.isArray(value)) {
+      const bad = value.findIndex((item) => !isSecure(item) && !readsAs(k.items!.type!, item));
+      if (bad >= 0) problems.push(`stack ${stack} sets ${k.key}[${bad}] to ${JSON.stringify(value[bad])}, which is not of type ${k.items.type}`);
+    }
+  }
+  return problems;
+}
+
+/** The project's file in `dir`, `Pulumi.yaml` or `Pulumi.yml`. */
+function projectFile(dir: string): string | undefined {
+  return ["Pulumi.yaml", "Pulumi.yml"].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+
+/** The stacks the project lists by their `Pulumi.<stack>.yaml` files in `dir`, sorted. */
+export function listedStacks(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .map((f) => /^Pulumi\.(.+)\.ya?ml$/.exec(f)?.[1])
+    .filter((s): s is string => s !== undefined)
+    .sort();
+}
+
+/** The stack file for `stack` in `dir`, if there is one. */
+function stackFile(dir: string, stack: string): string | undefined {
+  return [`Pulumi.${stack}.yaml`, `Pulumi.${stack}.yml`].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+
+// ── pulumi about ────────────────────────────────────────────────────
+
+/** What `pulumi about --json` reported, for the check report. */
+export interface PulumiAboutDetail {
+  engine: PulumiMemberEngine;
+  version?: string;
+  plugins: Array<{ name: string; version?: string }>;
+  backend?: { name?: string; url?: string; user?: string };
+}
+
+/** Read `pulumi about --json`'s document. Undefined when it is not JSON. */
+export function pulumiAboutDetail(engine: PulumiMemberEngine, stdout: string | undefined): PulumiAboutDetail | undefined {
+  if (!stdout) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(doc)) return undefined;
+  const cli = isRecord(doc.cli) ? doc.cli : {};
+  const plugins = Array.isArray(doc.plugins)
+    ? doc.plugins.filter(isRecord).map((p) => ({ name: String(p.name ?? ""), ...(typeof p.version === "string" ? { version: p.version } : {}) })).filter((p) => p.name)
+    : [];
+  const b = isRecord(doc.backend) ? doc.backend : undefined;
+  const backend = b
+    ? { ...(typeof b.name === "string" ? { name: b.name } : {}), ...(typeof b.url === "string" ? { url: b.url } : {}), ...(typeof b.user === "string" ? { user: b.user } : {}) }
+    : undefined;
+  return { engine, ...(typeof cli.version === "string" ? { version: cli.version } : {}), plugins, ...(backend ? { backend } : {}) };
+}
+
+// ── The steps ───────────────────────────────────────────────────────
+
+/** The last lines of what a failed run printed, for its reason. */
+function tail(text: string | undefined): string {
+  const lines = (text ?? "").trim().split("\n").filter(Boolean);
+  return lines.slice(-3).join(" | ");
+}
+
+export interface PulumiCheckStepsOptions {
+  /** The runner for an engine, given the check job's environment. Default {@link checkRunner}. */
+  runner?: (engine: PulumiMemberEngine, env: Record<string, string>) => PulumiRunner;
+}
+
+/** The steps for one member, in order: install, each stack's config, about. */
+export async function pulumiMemberCheck(member: CheckStageMember, ctx: Pick<CheckStepsContext, "env" | "log">, opts: PulumiCheckStepsOptions = {}): Promise<CheckStepOutcome[]> {
+  const fields = member.fields ?? {};
+  const declaredEngine = fields.engine === "pulumi" || fields.engine === "plunge" ? fields.engine : undefined;
+  const declaredStack = typeof fields.stack === "string" && fields.stack.length > 0 ? fields.stack : undefined;
+  const { engine } = pulumiMemberEngine(member.dir, declaredEngine, { env: ctx.env });
+  const run = (opts.runner ?? checkRunner)(engine, ctx.env);
+  const out: CheckStepOutcome[] = [];
+  const base = { lexicon: LEXICON, member: member.name };
+
+  const file = projectFile(member.dir);
+  if (!file) {
+    out.push({ ...base, step: "pulumi-install", exit: 1, outcome: "failed", reason: `member ${member.name} has no Pulumi.yaml in ${member.dir}` });
+    return out;
+  }
+
+  // pulumi install
+  let installed = true;
+  try {
+    await runCheckPulumi(run, ["install"], member.dir);
+    out.push({ ...base, step: "pulumi-install", exit: 0, outcome: "passed" });
+  } catch (err) {
+    installed = false;
+    const f = pulumiRunFailure(err);
+    const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || tail(f.stdout) || f.message;
+    out.push({ ...base, step: "pulumi-install", exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} install failed for member ${member.name}: ${why}` });
+  }
+
+  // Stack config, run by nothing but this module.
+  let schema: PulumiProjectSchema | undefined;
+  try {
+    schema = pulumiProjectSchema(parseYAML(readFileSync(file, "utf-8")));
+  } catch (err) {
+    out.push({ ...base, step: "stack-config", exit: 1, outcome: "failed", reason: `member ${member.name}: ${file} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+  }
+  if (schema) {
+    const stackDir = join(member.dir, schema.stackConfigDir);
+    const stacks = [...new Set([...listedStacks(stackDir), ...(declaredStack ? [declaredStack] : [])])].sort();
+    if (stacks.length === 0) out.push({ ...base, step: "stack-config", exit: 0, outcome: "skipped", reason: `member ${member.name} lists no stack (no Pulumi.<stack>.yaml in ${stackDir})` });
+    for (const stack of stacks) {
+      const at = stackFile(stackDir, stack);
+      let doc: unknown = {};
+      if (at) {
+        try {
+          doc = parseYAML(readFileSync(at, "utf-8"));
+        } catch (err) {
+          out.push({ ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}, stack ${stack}: ${at} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+          continue;
+        }
+      }
+      const problems = pulumiStackConfigProblems(schema, stack, doc);
+      out.push(
+        problems.length === 0
+          ? { ...base, step: "stack-config", stack, exit: 0, outcome: "passed" }
+          : { ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}: ${problems.join("; ")}`, detail: { problems } },
+      );
+    }
+  }
+
+  // pulumi about --json
+  if (!installed) {
+    out.push({ ...base, step: "pulumi-about", exit: 0, outcome: "skipped", reason: `member ${member.name}: ${engine} install failed, so about did not run` });
+    return out;
+  }
+  const aboutArgs = declaredStack ? ["about", "--json", "--stack", declaredStack] : ["about", "--json"];
+  const stackPart = declaredStack ? { stack: declaredStack } : {};
+  try {
+    const { stdout } = await runCheckPulumi(run, aboutArgs, member.dir);
+    const detail = pulumiAboutDetail(engine, stdout);
+    out.push(
+      detail
+        ? { ...base, step: "pulumi-about", ...stackPart, exit: 0, outcome: "passed", detail }
+        : { ...base, step: "pulumi-about", ...stackPart, exit: 1, outcome: "failed", reason: `${engine} about --json for member ${member.name} printed no JSON` },
+    );
+  } catch (err) {
+    const f = pulumiRunFailure(err);
+    // about exits non-zero when one of its reads fails (no backend login in a check job), and still prints what it read.
+    const detail = pulumiAboutDetail(engine, f.stdout);
+    if (detail) {
+      ctx.log(`pulumi check: ${engine} about for ${member.name} exited ${f.exitCode ?? 1} and reported: ${tail(f.stderr) || "no reason"}`);
+      out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "passed", detail });
+    } else {
+      const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || f.message;
+      out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} about failed for member ${member.name}${declaredStack ? `, stack ${declaredStack}` : ""}: ${why}` });
+    }
+  }
+  return out;
+}
+
+/** The pulumi lexicon's check steps, for `LexiconPlugin.checkSteps`. */
+export function pulumiCheckSteps(opts: PulumiCheckStepsOptions = {}): CheckStepsAdapter {
+  return {
+    lexicon: LEXICON,
+    kinds: ["pulumi"],
+    async run(ctx) {
+      const out: CheckStepOutcome[] = [];
+      for (const member of ctx.members) out.push(...(await pulumiMemberCheck(member, ctx, opts)));
+      return out;
+    },
+  };
+}

package/src/index.ts

@@ -132,3 +132,5 @@ export { parsePlungeAdoptView, pulumiAdoptDigest, adoptBucketTarget, type Plunge
 export { pulumiPreview as pulumiPreviewStep, pulumiDrift as pulumiDriftStep } from "./op/builders";
 // Pulumi and plunge exit statuses on chant's exit-code table (#4553).
 export { pulumiExitOf, pulumiPlanMoved, PULUMI_EXIT, PLUNGE_PLAN_MOVED_EXIT } from "./exit-codes";
+// Which stack outputs a preview changes, traced through the export (#4635).
+export { pulumiPlannedOutputChanges, type PulumiOutputChange, type PulumiPlannedOutputChanges } from "./planned-output-changes";

package/src/member-outputs.test.ts

@@ -11,8 +11,10 @@
  * program on floci (see their READMEs): `stack output --json
  * --show-secrets=false` prints a secret output as the string `"[secret]"`,
  * and `preview --json` plans no stack outputs, so a settled preview gives
- * the export's and a preview with changes leaves every output unknown. No
- * binary runs here.
+ * the export's. A preview with changes traces each output to the export's
+ * resources (#4635): the replaced VPC's and security group's ids, the
+ * deleted parameter's name and the deleted queue's URL are unknown, and the
+ * rest keep the export's value. No binary runs here.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -48,6 +50,9 @@ const withoutSecret = (file: string): Record<string, unknown> =>
   Object.fromEntries(Object.entries(JSON.parse(text(file, "stack-output.json")) as Record<string, unknown>).filter(([, v]) => v !== "[secret]"));
 const APPLIED = withoutSecret("pulumi-outputs");
 const PLUNGE_APPLIED = withoutSecret("plunge-outputs");
+/** The outputs preview-replaced.json moves (#4635): the replaced VPC's and security group's ids, the deleted parameter's name, the deleted queue's URL. */
+const MOVED = ["securityGroupId", "vpcId", "vpcParameterName", "workerQueueUrls"];
+const KEPT = Object.fromEntries(Object.entries(APPLIED).filter(([k]) => !MOVED.includes(k)));
 
 function fake(answer: (args: string[]) => string): { run: PulumiRunner; calls: string[][] } {
   const calls: string[][] = [];
@@ -126,11 +131,12 @@ describe("pulumiOutputSource", () => {
     expect(cli.calls).toEqual([["preview", "--json", "--show-sames", "--stack", "floci"]]);
   });
 
-  test("planned values: a preview with changes (a replaced VPC) leaves every output unknown, the secret neither known nor unknown", async () => {
+  test("planned values: a preview with changes (a replaced VPC) leaves the outputs it moves unknown and keeps the rest, the secret neither known nor unknown", async () => {
     const read = await previewPulumiMemberRead({ member: "aws", dir: AWS_DIR, run: awsCli({ preview: "preview-replaced.json" }).run });
     const planned = pulumiMemberPlannedOutputs("aws", { ...read, exported: JSON.parse(text("pulumi-outputs", "stack-export.json")) });
-    expect(planned).toMatchObject({ known: {}, unknown: Object.keys(APPLIED).sort(), changes: true, planDigest: read.part.member.planDigest });
+    expect(planned).toMatchObject({ known: KEPT, unknown: MOVED, changes: true, planDigest: read.part.member.planDigest });
     expect(planned.unknown).not.toContain("dbPasswordValue");
+    expect(planned.known).not.toHaveProperty("dbPasswordValue");
   });
 
   test("a member on plunge runs the same commands under plunge, never pulumi", async () => {
@@ -279,9 +285,9 @@ describe("dns against a Pulumi output (#4455)", () => {
     const records = set.members.find((m) => m.member === "records")!;
     expect(records.unknownInputs).toEqual(["aws.vpcId"]);
     expect(records.reads).toEqual([{ upstream: "aws", outputs: ["vpcId"], unknown: ["vpcId"] }]);
-    // Every output the stack publishes is unknown while its preview has changes: one hole each.
+    // Each output the preview moves is unknown while it has changes: one hole each (#4635).
     const holes = set.doc.members.find((m) => m.member === memberOutputsMemberName("aws"))!.holes;
-    expect(holes).toHaveLength(Object.keys(APPLIED).length);
+    expect(holes.map((h) => h.address)).toEqual(MOVED.map((o) => `aws.${o}`));
     expect(holes).toContainEqual({ address: "aws.vpcId", type: "output", reason: "aws.vpcId is known only after aws applies; what reads it is planned again then" });
 
     // Merged before aws's own pipeline applied: the read refuses, so records is blocked behind it.
@@ -307,6 +313,22 @@ describe("dns against a Pulumi output (#4455)", () => {
     expect(w.state.recordsRan).toEqual([]);
   });
 
+  test("a reader of an output the preview leaves alone plans now with the export's value (#4635)", async () => {
+    const w = world({ preview: "preview-replaced.json" });
+    const estate: DriverComponent[] = [
+      ESTATE[0]!,
+      { ...ESTATE[1]!, deploy: [{ phase: "Apply", steps: [{ kind: "fake-records", inputs: { bucket: { stackOutput: { stack: "aws", name: "siteBucketName" } } } }] }] } as DriverComponent,
+    ];
+    const plan = planFanOut({ components: estate, changed: ["aws"] });
+    const set = await planPrSet({ components: estate, plan, registry: w.registry, env: "local" });
+    expect(set.failed).toBe(false);
+    expect(w.state.recordsPlanned).toEqual([{ inputs: { bucket: "rec-ts-site" } }]);
+    const records = set.members.find((m) => m.member === "records")!;
+    expect(records.unknownInputs).toBeUndefined();
+    expect(records.reads).toEqual([{ upstream: "aws", outputs: ["siteBucketName"] }]);
+    expect(set.plannedOutputs).toEqual({ aws: Object.keys(KEPT).sort() });
+  });
+
   test("run refuses while the stack's preview has changes left", async () => {
     const w = world({ preview: "preview-replaced.json" });
     const capability = w.registry.resolve(MEMBER_OUTPUTS_KIND);

package/src/member-outputs.ts

@@ -19,6 +19,13 @@
  *   The plan digest is the member part's (`computePlanDigest("pulumi-preview",
  *   ...)`), so a preview that moves after review moves the consumer's digest.
  *
+ * A preview with changes that plans no stack outputs (every real one,
+ * #4475) traces each output to the export's resources
+ * (`./planned-output-changes.ts`, #4635): an output whose resources the
+ * preview leaves alone keeps the export's value, and the others are
+ * unknown. A stack that reads only unchanged outputs plans now; one that
+ * reads a changing one waits for the producer's `up`.
+ *
  * A member on plunge (`pulumiMemberEngine`: the member config, then a
  * `plunge` backend URL in `Pulumi.yaml`) runs the same two commands under
  * `plunge`.
@@ -39,6 +46,7 @@
 import type { DeployContext } from "@intentius/chant/components/capability";
 import type { EngineMemberRef, EngineOutputSource, EnginePlannedOutputs } from "@intentius/chant/components/verbs/member-outputs";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { pulumiPlannedOutputChanges, type PulumiOutputChange } from "./planned-output-changes";
 import { pulumiPlannedStackOutputs, pulumiExportedStackOutputs, type PulumiStackOutput } from "./stack-outputs";
 import { memberExportOf, previewPulumiMemberRead, pulumiMemberStackOutputs, type PulumiMemberEngine, type PulumiRunner } from "./run";
 import { isSecret } from "./values";
@@ -88,10 +96,16 @@ export function pulumiPartHasChanges(part: ChangeSetPart): boolean {
  * the preview's error. A preview that plans no stack outputs (no stack step,
  * or one without outputs, which is what a real `pulumi preview --json`
  * prints, #4475) gives the export's outputs when it plans nothing to apply,
- * since no apply will move them, and names every output the export holds
- * unknown otherwise, so nothing reads a value the preview did not plan.
+ * since no apply will move them. With changes, each output is traced to the
+ * export's resources (#4635, {@link pulumiPlannedOutputChanges}): the ones
+ * the preview leaves alone keep their value, and the rest are unknown, so
+ * nothing reads a value the preview may move. `outputChanges` lists each
+ * output's verdict and why.
  */
-export function pulumiMemberPlannedOutputs(member: string, read: { part: ChangeSetPart; preview: unknown; exported?: unknown }): EnginePlannedOutputs {
+export function pulumiMemberPlannedOutputs(
+  member: string,
+  read: { part: ChangeSetPart; preview: unknown; exported?: unknown; targeted?: boolean },
+): EnginePlannedOutputs & { outputChanges?: PulumiOutputChange[] } {
   const { part } = read;
   if (part.member.status === "failed" || part.member.planDigest === null) {
     throw new Error(`member-outputs: the preview of Pulumi member "${member}" failed: ${part.member.error ?? "no plan"}`);
@@ -101,7 +115,11 @@ export function pulumiMemberPlannedOutputs(member: string, read: { part: ChangeS
   if (planned === undefined) {
     const exported = read.exported === undefined ? [] : pulumiExportedStackOutputs(read.exported);
     if (!changes) return { known: knownValues(exported), unknown: [], planDigest: part.member.planDigest, changes };
-    return { known: {}, unknown: exported.filter((o) => !o.secret).map((o) => o.name), planDigest: part.member.planDigest, changes };
+    if (part.member.holes.length > 0 || read.exported === undefined) {
+      return { known: {}, unknown: exported.filter((o) => !o.secret).map((o) => o.name), planDigest: part.member.planDigest, changes };
+    }
+    const traced = pulumiPlannedOutputChanges({ part, exported: read.exported, ...(read.targeted ? { targeted: true } : {}) });
+    return { known: traced.known, unknown: traced.unknown, planDigest: part.member.planDigest, changes, outputChanges: traced.outputs };
   }
   const unknown = planned.filter((o) => o.unknown).map((o) => o.name);
   return { known: knownValues(planned), unknown, planDigest: part.member.planDigest, changes: changes || unknown.length > 0 };